Skip to main content

Full text of "Digital Research CP-M Plus Version 3 OS Users Programmers and System Guides"

m 

DIGITAL 
RESEARCH^ 

CP/M Plus™ 

(CP/M® Versions) 
Operating System 

User's Guide 

Programmer's Guide 

System Guide 



Is reprlrMed by Commodore Business Machines Inc. with the permission of Digital Research Inc 
P.O. Bo!( 579 
1 60 Central Avenue 
Pacific Grove, CA 93950 



] 

n 

1 
1 



COPYRIGHT 

Copyright© 1983 Digital Research Inc. All rights reserved. No part of this publication may be reproduced, 
transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in 
any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without 
the prior written permission of Digital Research Inc., Post Office Box 579, Pacific Grove, California 93950. 



DISCLAIMER 

DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO 
THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MER- 
CHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Digital Research Inc. reserves 
the right to revise this publication and to make changes from time to time in the content hereof without 
obligation of Digital Research inc. to notify any person of such revision or changes. 



NOTICE TO USER 

From time to time changes are made in the filenames and in the files actually included on the distribution disk. 
This manual should not be construed as a representation or warranty that such files or materials and facilities 
exist on the distribution disk or as pan of the materials and programs distributed. Most distribution disks 
include a ■■README.DOC" file. This file explains variations from the manual which do constitute modifica- 
tion of the manual and the items included therewith. Be sure to read this file before using the software. 



TRADEMARKS 

CBASIC, CP/M, Digital Research and its logo are registered trademarks of Digital Research Inc. CP/M Plus, 
LINK-80, MAC, MP/M, Pascal/MT+, PL/I-SO, RMAC, SID, and TEX-80 are trademarks of Digital Research 
Inc. Z80 is a registered trademark of Zilog, Inc. Intel is a registered trademark of Intel Corporation. MicroSoft 
is a registered trademark of MicroSoft Corporation. 

TheCP/M Plus {CP/M Version 3} Operating System User's Guide was printed in the United States of America, 



Foreword 



Welcome to the world of microcomputers opened to you by your eight-bit micro- 
processor. Welcome also to the world of application software accessible with your 
Digital Research CP/M Plus™ operating system, also called CP/M® 3. Digital Research 
designed CP/M 3 especially for the 8080, 8085, Z80® or equivalent microprocessor 
that is the heart of your computer. 

What CP/M 3 Does For You 

CP/M 3 manages and supervises your computer's resources, including memory and 
disk storage, the console (screen and keyboard), printer, and communications devices. 
It also manages information stored magnetically on disks by grouping this informa- 
tion into files of programs or data. CP/M 3 can copy files from a disk to your 
computer's memory, or to a peripheral device such as a printer. To do this, CP/M 3 
places various programs in memory and executes them in response to commands you 
enter at your console. 

Once in memory, a program executes through a set of steps that instruct your 
computer to perform a certain task. You can use CP/M 3 to create your own pro- 
grams, or you can choose from the wide variety of CP/M 3 application programs 
that entertain you, educate you, and help you solve commercial and scientific problems. 

What You Need to Run CP/M 3 on Your Computer 

Digital Research provides two kinds of CP/M 3 systems: banked and nonbanked. 
Your computer dealer can tell you if you have a banked or nonbanked system. The 
banked system requires more memory, but in turn provides more memory space for 
application programs. The banked version also has additional enhancements that are 
noted in the text. 

The minimum hardware requirement for both versions of CP/M 3 is a computer 
based on an 8080, 8085, or equivalent microprocessor, a console device (generally a 
keyboard and display device such as a CRT screen), and at least one floppy disk 
drive. To use all the capabilities of CP/M 3, you should have two disk drives. At 
least one should be a single density floppy drive, because CP/M 3 and most CP/M 
applications are distributed on single density floppy disks. 



The nonbanked system requires at least 32K (kilobytes) of Random Access Mem- 
ory (RAM). The larger banked system requires at least 96K of RAM. If you want to 
expand beyond these requirements, you will appreciate that the banked system can 
include up to sixteen banks of memory. 

CP/M 3 and its utility programs are distributed on two floppy disks. The system 
disk contains the operating system and the most commonly used utility programs. A 
second disk contains additional utilities. 

How To Use CP/M 3 Documentation 
The CP/M 3 documentation set includes three manuals: 

■ CPIM Plus (CP/M Version 3) Operating System User's Guide 

■ CP/M Plus (CP/M Version 3) Operating System Programmer's Guide 

■ Programmer's Utilities Guide for the CP/M Family of Operating Systems 

The CP/M Plus (CP/M Version 3) Operating System User's Guide introduces you 
to the CP/M 3 operating system and tells you how to use it. The User's Guide 
assumes that the version of CP/M 3 on your distribution disk is ready to run on your 
computer. To use this manual, you must be familiar with the parts of your computer, 
know how to set it up and turn it on, and how to handle, insert, and store disks. 
However, you do not need a great deal of experience with computers. 

The CP/M Plus (CP/M Version 3) Operating System Programmer's Guide presents 
information for application programmers who are creating or adapting programs to 
run under CP/M 3. TTie Programmer's Utilities Guide for the CP/M Family of Oper- 
ating Systems includes information on the CP/M assemblers and debuggers that expe- 
rienced programmers use to create new CP/M 3 programs. 

How This Guide is Organized 

This guide begins with simple examples, proceeds with basic concepts, then pre- 
sents a detailed reference section on commands. The first four sections describe 
CP/M 3 operation for the first-time user. Section 1 introduces CP/M 3 and tells you 
how to start the operating system, enter commands, edit the command line, and 
create back-up copies of your distribution disks. Section 2 discusses files, disks, and 
drives. Seaion 3 describes how you can use CP/M 3 to manage your printer and 
console. Seaion 4 develops the concepts you need to use CP/M 3 commands. If you 
are new to CP/M, read the first four sections carefully to get a general understanding 
of how to use CP/M 3 before you proceed to the specific command descriptions. 



Section 5 provides detailed information on each CP/M 3 utility program, arranged 
alphabetically for easy reference. Many of these are programming utilities that you 
will not use until you start writing your own CP/M 3 programs. Section 6 tells you 
how to use ED, the CP/M 3 file editor. With ED, you can create and edit program 
source codes, text, and data files. 

Appendix A lists the messages CP/M 3 displays when it encounters special condi- 
tions, and describes corrective action where necessary. Appendix B provides an ASCII 
to hexadecimal conversion table. Appendix C lists the filetypes associated with 
CP/M 3, Appendix D lists and defines the CP/M 3 control characters. Appendix E 
provides a glossary of commonly used computer terms. 

If you are new to computers, you might find some of the topics, such as the 
programming utilities, difficult to understand at first. Learning to use your computer 
is a challenge, and we hope you will find it fun. This book proceeds step-by-step so 
that you can quickly proceed from opening your new system disk package to master- 
ing CP/M 3's powerful facilities. 



] 

n 

1 
1 



Table of Contents 



1 Introduction 

1.1 How to Start CP/M 3 1-1 

1.2 The Command Line 1-2 

1.3 Why You Should Back Up Your Files 1-4 

1.4 How to Make Copies of Your CP/M 3 Disks 1-5 

2 Files, Disks, and Drives 

2.1 What is a File? 2-1 

2.2 How Are Files Created? 2-1 

2.3 How Are Files Named? 2-2 

2.4 Do You Have the Correct Drive? 2-3 

2.5 Do You Have the Correct User Number? 2-4 

2.6 Accessing More Than One File 2-5 

2.7 How to Protect Your Files 2-7 

2.7.1 File Attributes 2-7 

2.7.2 Date and Time Stamping 2-8 

2.7.3 Passwords (Banked CP/M 3 Only) 2-8 

2.8 How Are Files Stored on a Disk? 1-9 

2.9 Changing Floppy Disks 2-9 

2.10 Protecting a Drive 2-10 

3 Console and Printer 

3.1 Controlling Console Output 3-1 

3.2 Controlling Printer Output 3-1 

3.3 Console Line Editing 3-2 

3.3.1 Line Editing in Nonbanked CP/M 3 3-2 

3.3.2 Line Editing in Banked CP/M 3 3-4 

3.4 Redirecting Input and Output 3-6 

3.5 Assigning Logical Devices 3-9 

4 CP/M 3 Command Concepts 

4.1 Two Kinds of Commands 4-1 

4.2 Built-in Commands 4-1 

4.3 Transient Utility Commands 4-3 



Table of Contents (continued) 



4.4 How CP/M 3 Searches for Program and Data Files 4-4 

4.4.1 Finding Data Files 4-4 

4.4.2 Finding Program Flies 4-5 

4.5 Execuring Multiple Commands 4-7 

4.6 Terminating Programs 4-9 

4.7 Getting Help 4-9 

Command Summary 

5.1 Let's Get Past the Formalities 5-1 

5.2 How Commands Are Described 5-4 

The COPYSYS Command 5-9 

The DATE Command 5-11 

Display Current Date and Time 5-11 

Set the Date and Time 5-11 

The DEVICE Command 5-14 

Display Device Characteristics and Assignments 5-15 

Assign a Logical Device 5-16 

Set Attributes of a Physical Device 5-18 

Display or Set the Current Console Screen Size 5-18 

The DIR Command 5-19 

Display Directory 5-19 

Display Directory with Options 5-21 

The DUMP Command 5-29 

The ED Command 5-30 

The ERASE Command 5-38 

The GENCOM Command 5-40 

Attach RSX Files to a COM File 5-40 

Generate a COM File Using only RSX Files 5-41 

Restore a File with Attached RSXs to Original COM File 5-41 

Update (Add or Replace) RSX Files 5-42 

Attach a Header Record 5-42 

The GET Command 5-44 

Get Console Input from a File 5-44 

Terminate Console Input from a File 5-46 



Table of Contents (continued) 



The HELP Command 5-47 

Display Information 5-47 

Add Your Own Descriptions to the HELP.HLP File 5-48 

The HEXCOM Command 5-51 

The INITDIR Command 5-52 

The LIB Command 5-53 

The LINK Command 5-56 

The MAC Command 5-59 

The PATCH Command 5-62 

PIP Command 5-63 

Single File Copy 5-63 

Multiple File Copy 5-66 

Combining Files 5-67 

Copy Files to and from Auxiliary Devices 5-68 

Multiple Command Mode 5-70 

Using Options with PIP 5-71 

The PUT Command 5-77 

Direct Console Output to a File 5-78 

Put Printer Output to a File 5-79 

Terminate Console Output to a Fiie 5-79 

Terminate Printer Output to a File 5-80 

The RENAME Command 5-81 

The RMAC Command 5-84 

The SAVE Command 5-85 

The SET Command 5-86 

Sec File Attributes 5-86 

Set Drive Attribute 5-88 

Assign a Label to the Disk 5-88 

Assign Password to the Label 5-89 

Enable/Disable Password Protection for Files on a Disk 5-89 

Assign Passwords to Files 5-90 

Set Password Protection Mode for Files on a Disk 5-90 

Assign a Default Password 5-91 

Set Time Stamp Options on Disk 5-92 

Additional SET Examples 5-94 



Table of Contents (continued) 



The SETDEF Command 5-95 

Display the Program Loading Search Definitions 5-95 

Assign the Drive for Temporary Files 5-95 

Define the Disk Drive Search Order 5-96 

Define the Ftletypc Search Order 5-96 

Turn On/Off System Display Mode 5-97 

Turn On/Off System Page Mode 5-98 

The SHOW Command 5-99 

Display Access Mode and Disk Space Available 5-99 

Display Disk Label 5-99 

Display User Number Information 5-100 

Display Number of Free Directory Entries 5-101 

Display Drive Characteristics 5-102 

The SID Command 5-103 

SID Utilities 5-107 

The SUBMIT Command 5-109 

Program Input Lines in a SUB File 5-110 

The SUB File 5-111 

Executing the SUBMIT Command 5-112 

The PROFILE.SUB Start-up File 5-113 

The TYPE Command 5-114 

The USER Command 5-116 

The XREF Command 5-117 

6 ED, The CP/M 3 Context Editor 

6.1 Introduction to ED 6-1 

6.2 Starting ED 6-1 

6.3 ED Operation 6-3 

6.3.1 Appending Text into the Buffer 6-5 

6.3.2 ED Exit 6-6 

6.4 Basic Editing Commands 6-8 

6.4.1 Moving the Character Pointer 6-10 

6.4.2 Displaying Memory Buffer Contents 6-12 

6.4.3 Deleting Characters 6-13 

6.4.4 Inserting Characters into the Memory Buffer 6-14 

6.4.5 Replacing Characters 6-16 



Table of Contents (continued) 



6.5 Combining ED Commands 6-17 

6.5.1 Moving the Character Pointer 6-18 

6.5.2 Displaying Text 6-18 

6.5.3 Editing 6-19 

6.6 Advanced ED Commands 6-20 

6.6.1 Moving the CP and Displaying Text 6-20 

6.6.2 Finding and Replacing Character Strings 6-21 

6.6.3 Moving Text Blocks 6-26 

6.6.4 Saving or Abandoning Changes: ED Exit 6-27 

6.7 ED Error Messages 6-29 



Appendixes 

A CP/M 3 Messages A-1 

B ASCII and Hexadecimal Conversions B-1 

C Filetypes C-1 

D CP/M 3 Control Character Summary D-1 

E User's Glossary E-1 

List of Tables 

3-1. Nonbanked CP/M 3 Line-editing Control Characters 3-3 

3-2. Banked CP/M 3 Line-editing Control Characters 3-5 

3-3. CP/M 3 Logical Devices 3-9 

4-1. Built-in Commands 4-2 

4-2. Transient Utility Commands 4-3 

5-1. Reserved Characters 5-3 

5-2. CP/M 3 Filetypes 5-4 

5-3. Syntax Notation 5-5 



Table of Contents (continued) 



5-4. DEVICE Oprions 5-17 

5-5. DIR Display Options 5-22 

5-6. ED Command Summary 5-31 

5-7. GET Options 5-45 

5-8. LIB Options 5-54 

5.9. LIB Modifiers 5-54 

5.10. LINK Oprions 5-56 

5.11. Input/Output Options 5-60 

5.12. Output File Modifiers 5 

5. 1 3. PIP Options 5-72 

5.14. PUT Options 5 

5.15. RMAC Command Options 5 

5.16. SET Eile Attributes 5 

5.17. Password Protection Modes 5-91 

5.18. SID Commands 5-105 

6-1. Text Transfer Commands 6-5 

6-2. Basic Editing Commands ..,....,,,,. 6-9 

6-3. CP/M 3 Line-editing Controls 6-15 

6-4. ED Error Symbols 6-30 

6-5. ED Diskette File Error Messges 6-31 

A-1. CP/M 3 .Messages A-1 

B-1. ASCII Symbols B-1 

B-2. ASCII Conversion Table B-2 

C-1. Common Filetypes C-1 

D-1. Nonbanked CP/M 3 Control Characters D-I 

D-2. Banked CP/M 3 Line-editing Control Characters D-3 



Figure 

6-1. Overall ED Operation 



Section 1 
Introduction to CP/M 3 



This section tells you how to start CP/M 3, how to enter and edit the cotnmand 
line, and how to make back-up copies of your CP/M 3 distribution disks. 



1.1 How to Start CP/M 3 

Starting or loading CP/M 3 means reading a copy of the operating system from 
your CP/M 3 system disk (1 of 2 of your distribution disks} into your computer's 
memory. 

First, check that your computer's power is on. Next, insert the CP/M 3 system 
disk into your initial drive. In this section, assume that the initial drive is A and the 
disk is removable. Close the drive door. Then, press the RESET or RESTART button. 
This automatically loads CP/M 3 into memory. This process is called booting, cold 
starting, or loading the system. 

After CP/M 3 is loaded into memory, a message similar to the following is dis- 
played on your screen: 



The version number, represented above by V.V, tells you the version of CP/M 3 that 
you own. After this display, the following two-charaaer message appears on your 



This is the CP/M 3 system prompt. The system prompt tells you that CP/M 3 is 
ready to read a command from your keyboard. In this example, the prompt also tells 
you that drive A is your default drive. This means that until you tell CP/M 3 to do 
otherwise, it looks for program and data files on the disk in drive A. It also tells you 
that you are logged in as user 0, by the absence of a user number other than 0. 



H DIGITAL RESEARCH'" - 



1.2 The Commiuid Line CP/M 3 User's Guide 

1.2 The Command Line 

CP/M 3 performs tasks according to specific commands that you type at your 
keyboard. A CP/M 3 command line is composed of a command keyword, an optional 
command tail, and a carriage return keystroke. The command keyword identifies a 
command (program) to be executed. The command tail can contain extra informa- 
tion for the command, such as a filename or parameters. To end the command line, 
you must press the carriage return or ENTER key. The following example shows a 
command line. 

f\>OIR MYFILE 

The charaaers that the user types are slanted to distinguish them from characters 
that the system displays. In this example, DIR is the command keyword and MYFILE 
is the command tail. The carriage return keystroke does not appear on the screen or 
in the example. You must remember to press the carriage return key to send a 
command line to CP/M 3 for processing. Note that the carriage return key can be 
marked ENTER, RETURN, CR, or something similar on your keyboard. In this 
guide, RETURN signifies the carriage return key. 

As you type characters at the keyboard, they appear on your screen. The single- 
character position indicator, called the cursor, moves to the ri^t as you type char- 
acters. If you make a typing error, press either the BACKSPACE key (if your key- 
board has one) or CTRL-H to move the cursor to the left and correct the error. 
CTRL is the abbreviation for the Control key. To type a control charaaer, hold 
down the Control key and press the required letter key. For example, to move the 
cursor to the left, hold down CTRL and press the H key. 

You can type the keyword and command tail in any combination of upper-case 
and lower-case letters. CP/M 3 treats all leners in the command line as upper-case. 



Generally, you type a command hne directly after the system prompt. However, 
CP/M 3 does allow spaces between the prompt and the command keyword. 



- Si DIGITAL RESEARCH'" 



CP/M 3 User's Guide 1.2 The Command Line 

CP/M 3 recognizes two different types of commands: built-in commands and tran- 
sient utility commands. Built-in commands execute programs that reside in memory 
as a part of the CP/M 3 operating system. Built-in commands can be executed imme- 
diately. Transient utihty commands are stored on disk as program files. They must 
be loaded from disk to perform their task. You can recognize transient utility pro- 
gram files when a directory is displayed on the screen because their filenames are 
followed by COM. Seaion 4 presents lists of the CP/M 3 built-in and transient utility 
commands. 

For transient utilities, CP/M 3 checks only the command keyword. If you include 
a command tail, CP/M 3 passes it to the utility without checking it because many 
utilities require unique command tails. A command tail cannot contain more than 
128 characters. Of course, CP/M 3 cannot read either the command keyword or the 
command tail until you press the RETURN key. 

Let's use one command to demonstrate how CP/M 3 reads command lines. The 
DIR command, which is an abbreviation for direCTory, tells CP/M 3 to display a 
directory of disk files on your screen. Type the DIR keyword after the system prompt, 
omit the command tail, and press RETURN. 

Pt>DIR 

CP/M 3 responds to this command by writing the names of all the files that are 
stored on the disk in drive A. For example, if you have your CP/M 3 system disk in 
drive A, these filenames, among others, appear on your screen: 



COPYSYS 


con 


PIP 


con 


SET 


con 



i niCITAL RtSEARCH'" 



1.2 The Command Line CP/M 3 User's Guide 



CP/M 3 recognizes only correctly spelled command keywords. If you make a typ- 
ing error and press RETURN before correcting your mistake, CP/M 3 echoes the 
command line followed with a question mark. If you mistype the DIR command, as 
in the following example, CP/M 3 responds 

A>DJR 

DJR? 

to tell you that it cannot find the command keyword. To correct simple typing errors, 
use the BACKSPACE key, or hold down the CTRL key and press H to move the 
cursor to the left. CP/M 3 supports other control characters that help you efficiently 
edit command lines. Section 3 tells how to use control charaaers to edit command 
lines and other information you enter at your console. 

DIR accepts a filename as a command tail. You can use DIR with a filename to 
see if a specific file is on the disk. For example, to check that the transient utility 
program C0PYSYS.COM is on your system disk, type 

Pi>DIR C0PYSYS.COM 

CP/M 3 performs this task by displaying either the name of the file you specified, or 
the message 



Be sure you type at least one space after DIR to separate the command keyword 
from the command tail. If you do not, CP/M 3 responds as follows. 

e^>DJRC0PYSyS.C0t1 
DIRCDPYBYS.COM? 



1.3 Why You Should Back Up Your Files 

Humans have faults, and so do computers. Human or computer errors sometimes 
destroy valuable programs or data files. By mistyping a command, for example, you 
could accidentally erase a program that you just created or a data file that has been 
months in the making. A similar disaster could result from an electronic component 



B DIGITAL RESEARCH'" 



CP/M 3 User's Guide 1.3 Why You Should Back Up Your Files 

Data processing professionals avoid losing programs and data by making copies of 
valuable files. Always make a working copy of any new program that you purchase 
and save the original. If the program is accidentally erased from the working copy, 
you can easily restore it from the original. 

It is also wise to make frequent copies of new programs or data files as you 
develop them. The frequency of making copies varies with each programmer. How- 
ever, as a general rule, make a copy at the point where it takes ten to twenty times 
longer to reenter the information than it takes to make the copy. 

So far, we have not discussed any commands that change information recorded on 
your CP/M 3 system disk. Before we do, make a few working copies of the your 
distribution disks. 



1.4 How to Make Copies of Your CP/M 3 Disks 

To back up your CP/M 3 disks, you need two or more floppy disks for the back- 
ups. The back-up disks can be new or used. You might want to format new, or 
reformat used disks with the disk formatting program that accompanies your partic- 
ular computer. If the disks are used, be sure that there are no other files on the disks. 

If your computer's manufacturer has provided a special program to copy disks, 
you might use it to make back-ups of your distribution disks. Otherwise, use the 
COPYSYS and PIP utility programs found on your CP/M 3 distribution disks. PIP 
can copy alt program and data files, but only COPYSYS can copy the operating 
system. Note that the COPYSYS utility distributed by Digital Resarch only func- 
tions with eight-inch, single-density drives. However, your computer's manufacturer 
might have modified COPYSYS to work with your equipment. 

This section shows how to make distribution disk back-ups on a system that has 
two drives: drive A and drive B. Your drives mi^t be named with other letters from 
the range A through P. To make a copy of your CP/M 3 distribution system disk, 
labeled 1 of 2, first use the COPYSYS utility to copy the operating system loader. 
Make sure that your distribution system disk is in drive A, the default drive, and the 
blank disk is in drive B. Then enter the following command at the system prompt: 

(^> COPYSYS 



1.4 How to Copy Your CP/M 3 Disks CP/M 3 User's Guide 

CP/M 3 loads COPYSYS into memory and runs it. COPYSYS displays the following 
output on your screen. When the program prompts you, press RETURN only when 
you have verified that the correa disk is in the correct drive. 

Copysvs ye r 3.0 

Source driue name (or return for default) ?fl 

Source on A then tfpe return 

Funct ion compl ete 

Destination driue name (or return to reboot) ?6 

Destination on B then type return 

Funct i on cowpI ete 

Do you wish to copy CPM3.SYS?j'ps 

(CP/M 3 repeats the above prompts to copy CPM3.SYS.) 

fl> 

You now have a copy of the operating system only. To copy the remaining files from 
disk 1 of 2, enter the following PIP command, 

(\>PIP B!=ft:*.* 

This PIP command copies all the files in your disk directory to drive B from drive A. 
PIP displays the message COPYING followed by each filename as the copy operation 
proceeds. When PIP finishes copying, CP/M 3 displays the system prompt. 

Now you have an exact copy of the distribution disk 1 of 2 in drive B. Remove 
the original from drive A and store it in a safe place. If your original remains safe 
and unchanged, you can easily restore your CP/M 3 program files if something 
happens to your working copy. 



- SI DICITAI. RESEARCH'" 



CP/M 3 User's Guide 1.4 How to Copy Your CP/M 3 Disks 

Remove the copy from drive B and insert it in drive A. Use this copy as your 
CP/M 3 system disk to make more back-ups, to try the examples shown throughout 
this manual, and to start CP/M 3 the next time you turn on your computer. Cold 
Stan the computer to check copy operations. 

You still need to make a back-up copy of distribution disk 2 of 2. This disk 
contains programmer's utility programs and source files. Place another new or refor- 
matted disk in drive B. This time, type only the command keyword: 



PIP responds with an asterisk prompt, *. You can now remove disk 1 of 2 from 
drive A and insert the disk you want to copy, disk 2 of 2. Type the following PIP 
command after the asterisk prompt, for example, 



Again, PIP displays the message COPYING, followed by each filename. When PIP 
completes the copy and displays the asterisk prompt, press RETURN, CP/M 3 then 
displays the familiar A> system prompt. You now have a copy of disk 2 of 2 in 
drive B. Remove both 2 of 2 disks and store them in a safe place. You can now 
reinsert your working system disk and continue to use the system. 



End of Section 1 



i DIGITAL RESEARCH" - 



Section 2 
Files, Disks, and Drives 



CP/M 3's most important task is to access and maintain files on your disks. With 
CP/M 3 you can create, read, write, copy, and erase disk files. This section tells you 
what a file is, how to create, name, and access a file, and how files are stored on 
your disks. It also tells how to change disks and change the default drive. 



2.1 What is a File? 

A CP/M 3 file is a collection of related information stored on a disk. Every file 
must have a unique name because CP/M 3 uses that name to access that file. A 
directory is also stored on each disk. The directory contains a list of the filenames 
stored on that disk and the locations of each file on the disk. 

In general, there are two kinds of files: program (command) files and data files. A 
program file contains an executable program, a series of instructions that the com- 
puter follows step-by-step. A data file is usually a collection of information: a list of 
names and addresses, the inventory of a store, the accounting records of a business, 
the text of a document, or similar related information. For example, your computer 
cannot execute names and addresses, but it can execute a program that prints names 
and addresses on mailing labels. 

A data file can also contain the source code for a program. Generally, a program 
source file must be processed by an assembler or compiler before it becomes a pro- 
gram file. In most cases, an executing program processes a data file. However, there 
are times when an executing program processes a program file. For example, the 
copy program PIP can copy one or more program files. 



2.2 How Are Files Created? 

There are many ways to create a file. One way is to use a text editor. The CP/M 3 
text editor ED (described in Section 6) can create a file and assign it the name you 
specify. You can also create a file by copying an existing file to a new location, 
perhaps renaming it in the process. Under CP/M 3, you can use the PIP command to 
copy and rename files. Finally, some programs such as MAC™ create output files as 
they process input files. 

HI DIGITAL RESEARCH''- 



2.3 How Are Files Named? CP/M 3 User's Guide 

2.3 How Are Files Named? 

CP/M 3 identifies every file by its unique file specification. A file specification can 
be simply a one- to eight- character filename, such as: 



A file specification can have four parts; a drive specifier, a filename, a filetype, and 
a password. 

The drive specifier is a single letter (A-P) followed by a colon. Each drive in your 
system is assigned a letter. When you include a drive specifier as part of the file 
specification, you are telling CP/M 3 that the file is stored on the disk currently in 
that drive. For example, if you enter 

BiMYFILE 

CP/M 3 looks in drive B for die file MYFILE. 

The filename can be from one to eight characters. When you make up a filename, 
try to let the name tell you something about what the file contains. For example, if 
you have a list of customer names for your business, you could name the file: 



so that the name gives you some idea of what is in the file. 

As you begin to use your computer with CP/M 3, you will find that files fall 
naturally into categories. To help you identify files belonging to the same category, 
CP/M 3 allows you to add an optional one- to three- character extension, called a 
filetype, to the filename. When you add a filetype to the filename, separate the filetype 
from the filename with a period. Try to use three letters that tell something about 
the file's category. For example, you could add the following filetype to the file that 
contains a list of customer names: 

CUSTOMER. NAM 

When CP/M 3 displays file specifications in response to a DIR command, it adds 
blanks to short filenames so that you can compare filetypes quickly. The program 
files that CP/M 3 loads into memory from a disk have different filenames, but all 
have the filetype COM. 

m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 2.3 How Are Files Named? 

In banked CP/M 3, you can add a password as an optional part of the file specifi- 
cation. The password can be from one to eight characters. If you include a password, 
separate it from the Rietype (or filename, if no filetype is included) with a semicolon, 
as follows; 

CUSTOMER. nam; ACCOUNT 

If a file has been protected with a password, you must ENTER the password as part 
of the file specification to access the file. Section 2.7.3 describes passwords in more 
detail. 

We recommend that you create filenames, filetypes, and passwords from letters 
and numbers. You must not use the following characters in filenames, filetypes, or 
passwords because they have special meanings for CP/M 3: 

<> = ,!| * ?&/$[] ().: ;\+ - 

A complete file specification containing all possible elements consists of a drive 
specification, a primary filename, a filetype, and a password, all separated by their 
appropriate delimiters, as in the following example: 

A: DOCUMENT. lam; SUSAN 



2.4 Do You Have the Correct Drive? 

When you type a file specification in a command tail without a drive specifier, the 
program looks for the file in the drive named by the system prompt, called the 
default drive. For example, if you type the command 

A>Di'ff C0PYSYS.COM 

DIR looks in the direaory of the disk in drive A for COPYSYS.COM. If you have 
another drive, B for example, you need a way to tell CP/M 3 to access the disk in 
drive B instead. For this teason, CP/M 3 lets you precede a filename with a drive 
specifier. For example, in response to the command 

A>DI/? B:MYFILE.LIB 



IS DIGITAL RESEARCH" 



2.4 Do You Have the Corrca Drive? CP/M 3 User's Guide 

CP/M 3 looks for the file MYFILE.LIB in the directory of the disk in drive B. When 
you give a command to CP/M 3, note which disk is in the default drive. Many 
application programs require that the data files they access be stored in the default 
drive. 

You can also precede a program filename with a drive specifier, even if you use the 
program filename as a command keyword. For example, if you type the following 

command 



CP/M 3 looks in the directory of the disk in drive B for the file PIP.COM. If CP/M 3 
finds PIP on drive B, it loads PIP into memory and executes it. 

If you need to access many files on the same drive, you might find it convenient to 
change the default drive so that you do not need to repeatedly enter a drive specifier. 
To change the default drive, enter the drive specifier next to the system prompt and 
press RETURN. In response, CP/M 3 changes the system prompt to display the new 
default drive: 

A>6: 
B> 

Unlike the filename and filetype which are stored in the disk directory, the drive 
specifier for a file changes as you move the disk from one drive to another. Therefore, 
a file has a different file specification when you move a disk from one drive to 
another. Section 4 presents more information on how CP/M 3 locates program and 
data files. 



2.5 Do You Have the Correct User Number? 

CP/M 3 further idendfies all files by assigning each one a user number which 
ranges from to 15. CP/M 3 assigns the user number to a file when the file is 
created. User numbers allow you to separate your files into sixteen file groups. User 
numbers are particularly useful for organizing files on a hard disk. 

When you use a CP/M 3 utility to create a file, the file is assigned to the current 
user number, unless you use PIP to copy the file to another user number. You can 
determine the current user number by looking at the system prompt. 



a DIGITAL RESEARCH™ 



^ CP/M 3 User's Guide 2.5 Do You Have the Correcc User Number? 

! 

flA > User number 4, drive A 

M ft > User number 0, drive A 

2B > User number 2, drive B 

The user number always precedes the drive identifier. User 0, however, is the default 
user number and is not displayed in the prompt. 

You can use the built-in command USER to change the current user number. 

f\>USER 3 
3A> 

You can change both the user number and the drive by entering the new user 
number and drive specifier together at the system prompt: 

-; A>36.- 
I 1 3B> 

n Most commands can access only those files that have the current user number, For 

example, if the current user number is 7, a DIR command with no options displays 
only the files that were created under user number 7, However, if a file resides in 
user and is marked with a special file attribute, the file can be accessed from any 

^ user number. (Section 2,7.1 discusses file attributes.) 

— 2.6 Accessing More Than One File 

Certain CP/M 3 built-in and transient utilities can select and process several files 
__ when special wildcard characters arc included in the filename or filetype, A file spec- 
ification containing wildcards is called an ambiguous filespec and can refer to more 
than one file because it gives CP/M 3 a pattern to match. CP/M 3 searches the disk 
directory and selects any file whose filename or filetype matches the pattern. 



m DIGITAL RESEARCH'" 



2.6 Accessing Multiple Files CP/M 3 User's Guide 

The two wildcard characters are ?, which matches any single letter in the same 
position, and ', which matches any character at that position and any other charac- 
ters remaining in the filename or filetype. The following list presents the rules for 
using wildcards. 

■ A } matches any character in a name, including a space character. 

■ An * must be the last, or only, character in the filename or filetype. CP/M 3 
internally replaces an * with ? characters to the end of the filename or 
filetype. 

■ When the filename to match is shorter than eight characters, CP/M 3 treats 
the name as if it ends with spaces. 

■ When the filetype to match is shorter than three characters, CP/M 3 treats 
the filetype as if it ends with spaces. 

Suppose, for example, you have a disk that contains the following six files: 

fl.COM ftfl.COM flftfl.COM B.COM A . ASM and B . ASM 

The following wildcard specifications match all, or a portion of, these files: 

*.* is created as ????????.??? 

???????? . ??? matches all six names 

*.COM is treated as ????????.COM 

???????? . COM matches the first four names 

? . COM matches A.COM and B.COM 

?.* is treated as ?.??? 

? . ??? matches A.COM, B.COM, A.ASM, and B.ASM 

A? . COM matches A.COM and AA.COM 

ft*, COM is treated as A???????.COM 

fl???????.COM matches A.COM, AA.COM, andAAA.COM 

IB DIGITAL RESEARCH'" 



^ CP/M 3 User's Guide 2.6 Accessing Multiple Files 

I 

Remember that CP/M 3 uses wildcard patterns only while searching a disk direc- 

ntory, and therefore wildcards are valid only in filenames and filetypes. You cannot 
use a wildcard character in a drive specifier. You also cannot use a wildcard charac- 
ter as part of a filename or filetype when you create a file. 

1 2.7 How to Protect Your Files 

*^ Under CP/M 3 you can organize your files into groups to protect them from 

accidental change and from unauthorized access. You can specify how your files are 
displayed in response to a DIR command, and monitor when your files were last 

_ accessed or modified. CP/M 3 supports these features by assigning the following to 
< files: 

■ user numbers 
p[ ■ attributes 

I ( ■ time and date stamps 

■ passwords [banked CP/M 3 only) 

j 1 All of this information for each file is recorded in the disk direaory. 

_ 2.7.1 FUe Attributes 

File attributes control how a file can be accessed. When you create a file, CP/M 3 
gives it two attributes. You can change the attributes with a SET command, 

~ The first attribute can be set to either DIR (Directory) or SYS (System). This 

' attribute controls whether CP/M 3 displays the file's name in response to a DIR 

command or DIRSYS command. When you create a file, CP/M 3 automatically sets 

~ this attribute to DIR. You can display the name of a file marked with the DIR 
attribute with a DIR command. If you give a file the SYS anribute, you must use a 
DIRSYS command to display the filename. Simple DIR and DIRSYS commands dis- 

„^ play only the filenames created under the current user number. 

A file with the SYS attribute has a special advantage when it is created under user 
0. When you give a file with user number the SYS attribute, you can read and 

"" execute that file from any user number. This feature gives you a convenient way to 
make your commonly used programs available under any user number. Note, how- 
ever, that a user SYS file does not appear in response to a DIRSYS command unless 

— is the current user number. 



m DIGITAL RESEARCH'" 



2.7 How to Protea Your Files CP/M 3 User's Guide 

The second file attribute can be set to either R/W (Read-Write) or R/O (Read- 
only), If a file is marked R/O, any anempt to write data to that file produces a Read- 
only error message. Therefore, you can use the R/O attribute to protea important 
files. A file with the R/W attribute can be read or written to, or erased at any time, 
unless the disk is physically write -protected. 

2.7.2 Date and Time Stamping 

If you use date and time stamps, you can quickly locate the most recent copy of a 
file, and check when it was last updated or changed. You can choose to have the 
system tell you either when you created the file, or when you last read from or wrote 
to the file. You use the SET command to enable date and time stamping, and the 
DIR command with the DATE option to display a file's time and date stamp. 

A SET command enables the option you want to monitor. You can use the follow- 
ing commands to enable time and date stamping on a disk, but you must choose 
between ACCESS and CREATE. If you choose ACCESS, the stamp records the last 
time the file was accessed. If you choose CREATE, the stamp records when the file 
was created. 

Pi>SET CACCESS=ONJ 
Pi>SET CCREftTE-0N2 
f\>SET [UPDftTE=ONJ 

Files created on or copied to a disk that has time and date stamping are automati- 
cally stamped. The DATE command allows you to display and reset the time and 
date that CP/M 3 is using. For a complete discussion of time and date stamping, see 
the descriptions of the SET and INITDIR commands in Section 5. 

2.7.3 Passwords (Banked CP/M 3 Only) 

Passwords allow you to protect your files from access by other users. You can use 
passwords to limit access to certain files for security purposes. 

The SET utility allows you to enable password protection on a drive, assign a 
password to SET itself (so that unauthorized users cannot disable password protec- 
tion on a drive), and assign passwords to specific files that have already been created. 
You can assign passwords to all program and data files. This means that a command 
line could require the entry of two passwords in order to execute: one password to 
access the command program, and a second password to access the file specified in 
the command tail. 



1 DIGITAL RESEARCH™ 



CP/M 3 User's Guide 2.7 How to Protect Your Files 



Some CP/M 3 commands and most word processing, accounting, and other appli- 
cation programs running under CP/M 3 do not accept passwords in the command 
tail. If you want to protect your file and still use those programs, you can set a 
default password before executing the application program. See the description of 
the SET command in Section 5 for an explanation of this process. 



2.8 How Are Files Stored on a Disk? 

CP/M 3 records the filename, filetype, password, user number, and attributes of 
each file in a special area of the disk called the directory. In the direaory, CP/M 3 
also records which parts of the disk belong to which file. 

CP/M 3 allocates directory and storage space for a file as records are added to the 
file. When you erase a file, CP/M 3 reclaims storage in two ways: it makes the file's 
directory space available to catalog a different file, and frees the file's storage space 
for later use. It is this dynamic allocation feature that makes CP/M 3 powerful. You 
do not have to tell CP/M 3 how big your file will become, because it automatically 
allocates more storage for a file as needed, and releases the storage for reallocation 
when the file is erased. Use the SHOW command to determine how much space 
1 the disk. 



2.9 Changing Floppy Disks 

CP/M 3 cannot, of course, do anything to a file unless the disk that holds the file 
is inserted into a drive and the drive is ready. When a disk is in a drive, it is online 
and CP/M 3 can access its directory and files. 

At some time, you will need to take a disk out of a drive and insert another that 
contains different files. You can replace an online disk whenever you see the system 
prompt at your console. This is a clear indication that no program is reading or 
I writing to the drive. 

You can also remove a disk and insert a new one when an application program 

n prompts you to do so. This can occur, for example, when the data that the program 
uses does not fit on one floppy disk, 

,_ Note: you must never remove a disk if a program is reading or writing to it. 



a DIGITAL RESEARCH- 



Z9 Changing Floppy Disks CP/M 3 User's Guide 

You can change disks on the drive without sending any special signals to CP/M 3. 
This allows you to insert another disk at a program's request and read files from or 
create files on the new disk. 



2.10 Protecting a Drive 

Under CP/M 3, drives can be marked R/0 just as files can be given the R/O 
attribute. The default state of a drive is R/W. You can give a drive the R/O attribute 
by using the SET command described in Section 5. To return the drive to R/W, use 
the SET command or press a CTRL-C at the system prompt. 



End of Section 2 



m DIGITAL RESEARCH"* 



Section 3 
Console and Printer 



This section describes how CP/M 3 communicates with your console and printer, 
h tells how to start and stop console and printer output, edit commands you enter 
at your console, and redirect console and printer input and output. It also explains 
the concept of logical devices under CP/M 3. 



3.1 Controlling Console Output 

Sometimes CP/M 3 displays information on your screen too quickly for you to 
read it. Sometimes an especially long display scrolls off the top of your screen before 
you have a chance to study it. To ask the system to wait while you read the display, 
hold down the CONTROL (CTRL) key and press S. A CTRL-S keystroke causes the 
display to pause. When you are ready, press CTRL-Q to resume the display. If you 
press any key besides CTRL-Q during a display pause, CP/M 3 sounds the console 
bell or beeper. 

DIR, TYPE, and other CP/M 3 utilities support automatic paging at the console. 
This means that if the program's output is longer than what the screen can display 
at one time, the display automatically halts when the screen is filled. When this 
occurs, CP/M 3 prompts you to press RETURN to continue . 



3.2 Controlling Printer Output 

You can also use a control command to echo console output to the printer. To 
start printer echo, press a CTRL-P. To stop, press CTRL-P again. While printer echo 
is in effea, any characters that appear on your screen are listed at your printer. 

You can use printer echo with a DIR command to make a list of files stored on a 
floppy disk. You can also use CTRL-P with CTRL-S and CTRL-Q to make a hard 
copy of part of a file. Use a TYPE command to stan a display of the file at the 
console. When the display reaches the part you need to print, press CTRL-S to stop 
the display, CTRL-P to enable printer echo, and then CTRL-Q to resume the display 
and start printing. You can use another CTRL-S, CTRL-P, CTRL-Q sequence to 
terminate printer echo, 

18 DIGITAL RESEARCH"' 



3.3 Console Line Editing CP/M 3 User's Guide 

3.3 Console Line Editing 

You can correct simple typing errors with the BACKSPACE key, CP/M 3 also 
supports additional line-editing functions for banked and nonbanked systems that 
you perform with control characters. You can use the control characters to edit 
command lines or input lines to most programs. 

3.3.1 Line Editing in Nonbanked CP/M 3 

Nonbanked CP/M 3 allows you to edit your command line using the set of char- 
acters listed'in Table 3-1. To edit a command line in nonbanked CP/M 3, use control 
charaCTcrs to delete charaaers left of the cutsor, then replace them with new characters. 

In the following example command line, the command keyword PIP is mistyped. 
The underbar represents the cursor. 

A>PDP fl;=B -•♦.»_ 

To move the cursor to the letter O, hold down the CTRL key and press the letter H 
eleven times. CTRL-H deletes characters as it moves the cursor left, leaving the 
following command line: 



Now, type the correct letters, press RETURN, and send the command to CP/M 3. 

ft>PIP A:=B:*,* 



- m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 3-3 Console Line Editing 

Table 3-1 lists all line-editing control characters for nonbanked CP/M 3. 
Table 3-1. Nonbanked CP/M 3 Line-editing Control Characters 



Character 



Meaning 



CTRL-E Forces a physical carriage return but does not send the com- 

mand line to CP/M 3. Moves the cursor to the beginning of the 
next line without erasing your previous input. 

CTRL-H Deletes a character and moves the cursor left one character 

position. 

CTRL-1 Moves the cursor to the next tab stop. Tab stops are automati- 

cally set at each eighth column. Has the same effect as pressing 
the TAB key. 

CTRL-J Sends the command line to CP/M 3 and returns the cursor to 

the left of the current line. Has the same effen as a RETURN 
or a CTRL-M. 

CTRL-M Sends the command line to CP/M 3 and returns the cursor to 

the left of the current line. Has the same effect as a RETURN 
or a CTRL-J. 

CTRL-R Places a # at the current cursor location, moves the cursor to 

the next tine, and displays any partial command you typed so 

far. 

CTRL-U Discards all the characters in the command line, places a # at 

the current cursor position, and moves the cursor to the next 
command line. 

CTRL-X Discards all the characters in the command line, and moves the 

cursor to the beginning of the current line. 



You probably noticed that some control characters have the same meaning. For 
example, the CTRL-j and CTRL-M keystrokes have the same effea as pressing the 
RETTJRN key; all three send the command line to CP/M 3 for processing. Also, 
CTRL-H has the same effect as pressing the BACKSPACE key. 



m DIGITAL RESEARCH''' 



3.3 Console Line Editing CP/M 3 User's Guide 

3.3.2 Line Editing in Banked CP/M 3 

Banked CP/M 3 allows you to edit your command line without deleting all char- 
acters. Using the line-editing control characters listed in Table 3-2, you can move the 
cursor left and right to insert and delete characters in the middle of a command line. 
You do not have to retype everything to the right of your correction. In banked 
CP/M 3, you can press RETURN when the cursor is in any position in the command 
hne; CP/M 3 reads the entire command line. You can also recall a command for 
reediting and reexecution. 

In the following sample session, the user mistyped PIP, and CP/M 3 returned an 
error message. The user recalls the erroneous command line by pressing CTRL-W 
and corrects the error {the underbar represents the cursor): 

A>PDP A!=B!».*_ {PIP mistyped) 

POP? 

P>>POP A:=B:*.*_ (CTRL-W recalls the line) 

ft yPOP Ai=B:*.* {CTRL-B to beginning of line) 

ft > POP fl : =0 J # . * {CTRL-F to move cursor right) 

f^ypp fl ; =6 J * . * (CTRL-G to delete error) 

(\>PIP fl;=B:*.* (type I to correct the command name) 

To execute the corrected command line, the user can press return even though the 
cursor is in the middle of the line. A return keystroke, or one of its equivalent control 
characters, not only executes the command, but also stores the command in a buffer 
so that you can recall it for editing or reexecution by pressing CTRL-W. 

When you insert a character in the middle of a line, characters to the right of the 
cursor move to the right. If the line becomes longer than your screen is wide, char- 
acters disappear off the right side of the screen. These characters are not lost. They 
reappear if you delete characters from the line or if you press CTRL-E when the 
cursor is in the middle of the line. CTRL-E moves all characters to the right of the 
cursor to the next line on the screen. 

Table 3-2 gives a complete list of line-editing control charaaers for a banked 
CP/M 3 system. 

SI DlGfTAL RESEARCH'" 



CP/M 3 User's Guide 



3.3 Console Line Editing 



Table 3-2. Banked CP/M 3 Line-editing Control Characters 



Meaning 



CTRL-A Moves the cursor one character to the left. 

CTRL-B Moves the cursor to the beginning of the command Hne without 

having any effect on the contents of the Hne. If the cursor is at 
the beginning, CTRL-B moves it to the end of the line. 

RL-E Forces a physical carriage return but does not send the com- 

mand line to CP/M 3. Moves the cursor to the beginning of the 
next Hne without erasing the previous input. 

CTRL-F Moves the cursor one character to the right. 

CTRL-G Deletes the character indicated by the cursor. The cursor does 

not move. 

RL-H Deletes a character and moves the cursor left one character 

position. 

RL-I Moves the cursor to the next tab stop. Tab stops are automati- 

cally set at each eighth column. Has the same effect as pressing 
the TAB key. 

RL-J Sends the command line to CP/M 3 and returns the cursor to 

the beginning of a new line. Has the same effect as a RETURN 
or a CTRL-M keystroke. 

CTRL-K Deletes to the end of the line from the cursor. 

CTRL-M Sends the command line to CP/M 3 and returns the cursor to 

the beginning of a new line. Has the same effect as a RETURN 
or a CTRL-J keystroke. 



Retypes the command line. Places a # at the current cursor 
location, moves the cursor to the next line, and retypes any 
partial command you typed so far. 



m DIGITAL RESEARCH'- 



3.3 Console Line Editing 



CP/M 3 User's Guide 



Table 3-2. (continued) 



Meaning 



Discards all the characters in the command line, places a # at 
the current cursor position, and moves the cursor to the next 
hne. However, you can use a CTRL-W to recall any characters 
that were to the left of the cursor when you pressed CTRL-U. 

Recalls and displays previously entered command line both at 
the operating system level and within executing programs, If the 
CTRL-W is the first character entered after the prompt. CTRL- 
J, CTRL-M, CTRL-U, and RETURN define the command line 
you can recall. If the command line contains characters, CTRL- 
W moves the cursor to the end of the command line. If you 
press RETURN, CP/M 3 executes the recalled command. 



Discards all the characters left of the cursor and moves the cur- 
sor to the beginning of the current line. CTRL-X saves any 
s right of the cursor. 



You probably noticed that some control characters have the same meaning. For 
example, the CTRL-J and CTRL-M keystrokes have the same effect as pressing the 
RETURN key; all three send the command line to CP/M 3 for processing. Also, 
CTRL-H has the same effea as pressing the BACKSPACE key. Notice that when a 
control character is displayed on your screen, it is preceded by an up-arrow, I. For 
example, a CTRL-C keystroke appears as TC on your screen. 



3.4 Redirecting Input and Output 

CP/M 3's PUT command allows you to direct console or printer output to a disk 
file. You can use a GET command to make CP/M 3 or a utility program take console 
Input from a disk file. The following examples illustrate some of the conveniences 
GET and PUT offer. 



- m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



3.4 Redirecting Input/Output 



You can use a PUT command to direct console output to a disk file as well as the 
console. With PUT, you can create a disk file containing a directory of all files on that 
disk, as follows: 



fl 


DIR 


A 


FILENAME TEX 


A 


FOUR TEX 


n 


TWO TEX 


ft 


TYPE DIff.PRN 


A 


FILENAME TEX 


n 


FOUR TEX 


" 


TWO TEX 




You can use a 




the printer. 



I FRONT 
I LINEDIT 
! EXAMPZ 



I FRONT 
I LINEDIT 
I EXAnP2 



; EXAMPl TXT : 



r PUT command to direct printer output to a disk file as well 



A GET command can direct CP/M 3 or a program to read a disk file for console 
input instead of the keyboard. If the file is to be read by CP/M 3, it must contain 
standard CP/M 3 command lines. If the file is to be read by a utility program, it must 
contain input appropriate for that program. A file can contain both CP/M 3 com- 
mand lines and program input if it also includes a command to start a program. 

You add or omit the SYSTEM option in the GET command line to specify whether 
CP/M 3 or a utility program is to start reading the file, as shown in the following 
sample session. If you omit the SYSTEM option, the system prompt returns so that 
you can initiate the program that is to take input from the specified file. If you 
include the SYSTEM option, CP/M 3 immediately takes input from the specified file. 



19 DlCrTAL RESEARCH" - 



3.4 Redirecting Input/Output CP/M 3 User's Guide 



3A>yrl comolt inout from file Pi^.dat 
Gettinj coniolf inpul from file PIP.DflT 



3fl)tfpe csp.di\ 



fl: FILENAME TEX ; FRONT TEX ! FRONT BflK i ONE BflK ; THREE TEX 

fl! FOUR TEX 1 ONE 

fl! TWO TEX ! EXflMP3 

fl! THREE BflK i EXflNPS 



NON-SYSTEM FILE(S) EXIST 

See the descriptions of GET and PUT in Section 5 for more ways to use redirected 
input and output. 



iB DIGITAL RESEARCH™ 



"■ CP/M 3 User's Guide 



3.5 Assigning Logical Devices 



3.5 Assigning Logical Devices 

Most CP/M 3 computer systems have a traditional console with a keyboard and 
screen display. Many also have letter- quality printers. If you use your computer for 
unusual tasks, you might want to add a different kind of character device to your 
system: a line printer, a teletype terminal, a modem, or even a joystick for playing 
games. To keep track of these physically different input and output devices, CP/M 3 
associates different physical devices with logical devices. Table 3-3 gives the names 
of CP/M 3 logical devices. It also shows the physical devices assigned to these logical 
devices in the distributed CP/M 3 system. 



Table 3-3. CP/M 3 Logical Devices 



Logical 
Device Name 


Device Type 


Physical Device 
Assignment 


CONIN: 


Console input 


Keyboard 


CONOUT; 


Console output 


Screen 


AUXIN: 


Auxiliary input 


Null 


AUXOUT: 


Auxiliary output 


Null 


LST: 


List output 


Printer 



In some implementations of CP/M 3, you can change these assignments with a 
DEVICE command. If your system supports the DEVICE command, you can, for 
example, assign AUXIN and AUXOUT to a modem so that your computer can 
communicate with others over the telephone. 



End of Section 3 



] 

n 

1 
1 



Section 4 
CP/M 3 Command Concepts 



As we discussed in Section 1, a CP/M 3 command line consists of a command 

keyword, an optional command tail, and a carriage return keystroke. This section 
describes the two kinds of programs the command keyword can identify, and tells 
how CP/M 3 searches for a program file on a disk. This section also tells how to 
execute multiple CP/M 3 commands, and how to reset the disk system. 



4,1 Two Kinds of Commands 

A command keyword identifies a program that resides either in memory as part of 
CP/M 3, or on a disk as a program file. Commands that identify programs in mem- 
ory are called built-in commands. Commands that identify program files on a disk 
are called transient utility commands. 

CP/M 3 has six built-in commands and over twenty transient utility commands. 
You can add utilities lo your system by purchasing various CP/M 3-compatible appli- 
cation programs. If you are an experienced programmer, you can also write your 
own utilities that operate with CP/M 3. 



4.2 Built-in Commands 

Built-in commands are part of CP/M 3 and are always available for your use 
regardless of which disk you have in which drive. Built-in commands reside in mem- 
ory as a part of CP/M 3 and therefore execute more quickly than the transient 
utilities. 

Some built-in commands have options that require support from a related transient 
utility. The related transient has the same name as the built-in and has a filetype of 
COM. This type of transient utility is loaded only when a built-in command line 
contains options that cannot be performed by the built-in command. 



m DIGITAL RESEARCH'" 



4.2 Built-in Commands 



CP/M 3 User's Guide 



If you include certain options in the command tail for a built-in command, 
CP/M 3 might return a .COM Reiui red message. This means that the command 
tail options require suppon from a related transient utility and CP/M 3 could not 
find that program file. The following files must be accessible to support all the 
functions these built-ins offer: ERASE.COM, RENAME, COM, TYPE.COM, and 
DIR.COM. 



Section 5 e 



n detail the built-in commands listed in Table 4-1. 





Table 4-1. Built-in Commands 


Command 


Function 


DIR 


Displays filenames of all files in the directory except those marked 
with the SYS attribute. 


DIRSYS 


Displays filenames of files marked with the SYS (system) attri- 
bute in the directory. 


ERASE 


Erases a filename from the disk direaory and releases the stor- 
age space occupied by the file. 


RENAME 


Renames a disk file. 


TYPE 


Displays contents of an ASCII (TEXT) file at your screen. 


USER 


Changes to a different user number. 



CP/M 3 allows you to abbreviate the built-in commands as follows; 

DIRSYS DIRS 

ERASE ERA 

RENAME REN 

TYPE TYP 

USER USE 



m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



4.3 Transient Utility Commands 



4.3 Transient Utility Commands 

When you enter a command keyword that identifies a transient utility, CP/M 3 
loads the program file from the disk and passes it any filenames, data, or parameters 
you entered in the command tail. Section 5 provides the operating details for the 
CP/M 3 transient utihties listed in Table 4-2. 



Table 4-2. Transient Utility Commands 



Name 


Function 


COPYSYS 


Creates a new boot disk. 


DATE 


Sets or displays the date and time. 


DEVICE 


Assigns logical CP/M devices to one or more physical devices, 
changes device driver protocol and baud rates, or sets console 




screen size. 


DUMP 


Displays a file in ASCII and hexadecimal format. 


ED 


Creates and alters character files. 


GET 


Temporarily gets console input from a disk file rather than the 
keyboard. 


HELP 


Displays information on how to use CP/M 3 commands. 


HEXCOM 


Uses the output from MAC to produce a program file. 


INITDIR 


Initializes a disk directory to allow time and date stamping. 


LINK 


Links REL (relocatable) program modules produced by RMAC" 
[relocatable macro assembler) and produces program files. 


MAC 


Translates assembly language programs into machine code form. 


PIP 


Copies files and combines files. 



i DIGITAL RESEARCH™ 



4.3 Transient Utility Commands 



CP/M 3 User's Guide 



Table 4-2. (continued) 



Name 


Function 


PUT 


Temporarily directs printer or console output to a disk file. 


RMAC 


Translates assembly language programs into relocatable pro- 
gram modules, 


SET 


Sets file options including disk labels, file attributes, type of 
time and date stamping, and password protection. 


SETDEF 


Sets system options including the drive search chain. 


SHOW 


Displays disk and drive statistics. 


SID 


Helps you check your programs and interactively correct pro- 
gramming errors. 


SUBMIT 


Automatically executes multiple commands. 


XREF 


Produces a cross-reference list of variables used in an assembler 




program. 



4.4 How CP/M 3 Searches for Program and Data Files 

This section describes how CP/M 3 searches for program and data files on disk. If 
it appears that CP/M 3 cannot find a program file you specified in a command hne, 
the problem might be that CP/M 3 is not looking on the drive where the file is 
stored. Therefore, you need to understand the steps CP/M 3 follows in searching for 
program and data files. 

4.4.1 Finding Data Files 

As you recall, when you enter a command line, CP/M 3 passes the command tail 
to the program identified by the command keyword. If the command tail contains a 
file specification, the program calls CP/M 3 to search for the data file. If CP/M 3 
cannot find the data file, the program displays an error message at the console. 
Typically, this message is File not found or No File, but the message depends 
on the program identified by the command keyword. 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 4.4 How CP/M 3 Searches for Files 

If you do not include a drive specifier with the filename in a command tail, 
CP/M 3 searches the directory of the current user number on the default drive. If the 
file is not there, CP/M 3 looks for the file with the SYS attribute in the directory of 
user on the default drive. If CP/M 3 finds the file under user 0, it allows the 
program Read-Only access to the file. For example, if you enter the following com- 
mand line, 

3(\>TYPE MYFILE. TXT 

CP/M 3 first searches the directory for user 3 on drive A. If it docs not find 
MYFILE.TXT there, it searches the directory of user on drive A for MYFILE.TXT 
marked with the SYS attribute. If the file is not in either directory, CP/M 3 returns 
control to TYPE, which then displays No File. 

Some CP/M 3 utilities, such as PIP and DIR, restria their file search to the current 
user number. Because CP/M 3 does not allow Read- Write access to SYS files, ERASE 
and RENAME also restrict their search to the current user number. 

The search procedure is basically the same if you do include a drive specifier with 
the filename. CP/M 3 first looks in the directory of the current user number on the 
specified drive. Then, if it does not find the file, it looks in the directory for user 
on the specified drive for the file with the SYS attribute. If CP/M 3 does not find the 
data file after these two searches, it displays an error message. 

4.4.2 Finding Program Files 

The search procedure for a program file can be very different from a data file 
search. This is because you can use the SETDEF command described in Section 5 to 
define the search procedure you want CP/M 3 to follow when it is looking for a 
program file. With SETDEF you can ask CP/M 3 to make as many as sixteen searches 
when you do not include a drive specifier before the command keyword, but that is 
a rare case! We will begin by describing how CP/M 3 searches for program files 
when you have not yet entered a SETDEF command. 

If a command keyword identifies a transient utility, CF/M 3 looks for that program 
file on the default or specified drive. It looks under the current user number, and 
then under user for the same file marked with the SYS attribute. At any point in 
the search process, CP/M 3 stops the search if it finds the program file. CP/M 3 then 
loads the program into memory and executes it. When the program terminates, 
CP/M 3 displays the system prompt and waits for your next command. However, if 
CP/M 3 does not find the command file, it repeats the command line followed by a 
question mark, and waits for your next command. 

B DIGITAL RESEARCH™ 



4.4 How CP/M 3 Searches for Files CP/M 3 User's Guide — 

If you include a drive specifier before the command keyword, you are telling 
CP/M 3 precisely where to look for the program file. Therefore, CP/M 3 searches ~ 
only two locations: the directory for the current user on the specified drive, and then 
for user on the specified drive, before it repeats the command line with a question 
mark. For example, if you enter — 

HOAtSHOU CSPflCE] 

CP/M 3 looks on drive A, user 4 and then user for the file SHOW.COM. 

If you do not include a drive specifier before the command keyword, CP/M 3 
searches directories in a sequence called a drive chain. When you first receive "" 
CP/M 3, there is only one drive in your chain, the default drive. Unless you change 
the chain with a SETDEF command, CP/M 3 looks in two places for the program 
file. For example, if you enter — 

7E>SH0W CSPACEJ 

CP/M 3 searches the following locations for the file SHOW.COM: " 

1 . drive E, user 7 

2. drive E, user 

Remember that a SHOW.COM file under user must be marked with the SYS 
attribute or else CP/M 3 cannot find it. Use a SET command to give program files — 
under user to the SYS attribute because they can then be accessed automatically 
from all other user areas. You do not have to duplicate frequently used program files 
in all user areas on all drives. _ 

When you use a SETDEF command to define your own drive chain, include the 
default drive, and the drive that contains your most frequently used utilities. For an 
example, assume you defined your drive chain as * [the default drive) and drive A. "^ 
When you enter the following command: 

2D>SH0U ESPfiCEJ _ 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 4.4 How CP/M 3 Searches for FUes 

CP/M 3 looks for SHOW.COM in the following sequence; 

1. drive D, user 2 

2. drive D, user 

3. drive A, user 2 

4. drive A, user 

You can include your default drive in your drive chain with an option in a SETDEF 
command. Any drive chain you specify with SETDEF remains in effect until you 
restart or reset the system. 

You can also use a SETDEF command to enable automatic submit in your drive 
chain. See Section 4.5 for a description of automatic submit. 

4.5 Executing Multiple Commands 

In the examples so far, CP/M 3 has executed only one command at a time. 
CP/M 3 can also execute a sequence of commands. You can enter a sequence of 
commands at the system prompt, or you can put a frequently needed sequence of 
commands in a disk file. Once you have stored the sequence in a disk Hie, you can 
execute the sequence whenever you need to with a SUBMIT command. 

To enter multiple commands at the system prompt, separate each command key- 
word and associated command tail from the next keyword with an exclamation 
point, !. When you complete the sequence, press RETURN. CP/M 3 executes your 



TXT i EXflMPS i EXflhPZ TXT : EXflMPfl 



commands 


in order: 


3fl>rfirsri/ 


ir *)-a«.r#,#.'s 


NON-SVSTEn 


FlLEfS) EXIST 


3fl>dir e»a 


p».» 


ft! EXflMP? 


I EXflMPl 


A: EXftMPS 


! EXflHPG 



HI DIGITAL RESEARCH™ 



4.5 Executing Multiple Commands CP/M 3 User's Guide ~" 

If you find you need to execute the same command sequence frequently, stote the 
sequence in a disk file. To create this file, use ED or another character file editor. ~ 
The file must have a filetype of SUB. Each command in the file must start on a new 
line. For example, an UPDATE.SUB file might look like this: 

DIR A:«.C:OM 
ERA B!».CDM 

PIP B:=ft!«.COM ^ 

To execute this list, enter the following command: 

f\> SUBMIT UPDATE — 

The SUBMIT utility passes each command to CP/M 3 for sequential execution. While 
SUBMIT executes, the commands arc usually echoed at the console, as well as any _ 
program's screen display, such as the directory or PIP's "COPYING..." message. 
When one command completes, the system prompt reappears either with the next 
command in the SUB file, or, when the SUB file is exhausted, by itself to wait for 
your next command from the keyboard. "" 

If PROFILE exists, PROFILE.SUB is a special submit file that CP/M 3 automati- 
cally executes at each cold start. This feature is especially convenient if you regularly — 
execute a standard set of commands, such as SETOFF and DATE SET, before begin- 
ning a work session. A PROFILE.SUB might already exist on your distribution disk. 
If not, you can create one using ED or another editor. _ 

The description of the SUBMIT utility in Section 5 gives more details on how to 
create a SUB file and use SUBMIT parameters to pass options to the programs to be 
executed. "■ 

You can also use CTRL-C to reset the disk system. This is sometimes called a 
warm start. When you press CTRL-C and the cursor is at the system prompt, — 
CP/M 3 logs out all the active drives, then logs in the default drive. The active drives 
arc any drives you have accessed since the last cold or warm start. A SHOW [SPACE] 
command displays the remaining space on all active drives. In the following example, 
SHOW [SPACE] indicates that three drives are active. However, if you press CTRL-C ~ 
immediately after this display and then enter another SHOW [SPACE] command, only 
the space for the default drive. A, is displayed. 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 4.6 Terminating Programs 

4.6 Terminating Programs 

You can use the two keystroke command CTRL-C to terminate program execution 
or reset the disk system. To enter a CTRL-C command, hold down the CTRL key 
and press C. 

Not all application programs that run under CP/M can be terminated by a 
CTRL-C. However, most of the transient utilities supplied with CP/M 3 can be 
terminated immediately by a CTRL-C keystroke. If you try to terminate a program 
while it is sending a display to the screen, you might need to press a CTRL-S to halt 
the display before entering CTRL-C. 

You can also use CTRL-C to reset the disk system. This is sometimes called a 
warm start. When you press CTRL-C and the cursor is at the system prompt, 
CP/M 3 logs out all the active drives, then logs in the default drive. The active drives 
are any dtives you have accessed since the last cold or warm start. A SHOW [SPACE] 
command displays the remaining space on all active drives. In the following exam- 
ple, SHOW [SPACE] indicates that three drives are active. However, if you press 
CTRL-C immediately after this display and then enter another SHOW [SPACE] 
command, only the space for the default drive, A, is displayed. 



A > SHOW 


[SPACEJ 






A: RM t 


Space: 


9 


<<988K 


B: RO . 


Space: 


2 


45aK 


Ci RO » 


Space: 


1 


GGSk 


fl>'C 








A > SHOW 


[SPACE] 






A: RM. 


Space: 


3 


48Bk 



4.7 Getting Help 

CP/M 3 includes a transient utility command called HELP that can display a 
summary of what you need to know to use each command described in this manual. 
To get help, simply enter the command: 



m DIGITAL RESEARCH'- 



4.7 Getting Help CP/M 3 User's Guide 

In response, the HELP utility displays a list of topics for which summaries are 
available. After HELP lists the topics available, it displays its own prompt: 

HELP> 

To this prompt, you can enter one of the topics presented in the list, for example, 

HELP>SHOW 

After displaying a summary of the SHOW command, HELP lists subtopics that detail 
different aspects of the SHOW command. To display the information on a subtopic 
when you have just finished reading the main topic, enter the name of the subtopic 

preceded by a period. 

HELPy, OPTIONS 

In the preceding example, HELP then displays the options available for the SHOW 
command. As you become familiar with HELP, you might want to call a HELP 
subtopic directly from the system prompt as follows: 

P>>HELP SHOhl OPTIONS 

HELP lets you learn the basic CP/M 3 commands quickly. You might find that 
you reference the command summary in Section 5 only when you need details not 
provided in the HELP summaries. When you add new utilities, you can modify HELP 
to add or subtract topics, or even modify the summaries HELP presents. See the 
description of HELP in Section 5 for complete details. 



End of Section 4 



H DIGITAL RESEARCH" 



Section 5 
Command Summary 



This section describes the commands and programs supplied with your CP/M 3 
operating system. The commands are in alphabetical order. Each command is fol- 
lowed by a short explanation of its operation and examples. More complicated com- 
mands are described later in detail. For example, ED is described in Section 6. Other 
commands, such as SID and MAC, are described fully in other CP/M manuals. 

CP/M 3 has replaced some commands from previous CP/M versions. MAC replaces 
ASM; SHOW and DIR include the previous STAT funaions; and SID replaces DDT. 



5.1 Let's Get Past the Formalities 

This section describes the parts of a file specification in a command line. There are 
four pans in a file specification; to avoid confusion, each part has a formal name: 

■ drive specifier — the optional disk drive A, B, C, ...P that contains the file or 
group of files to which you arc referring. If a drive specifier is included in 
your command line, a colon must follow it. 

■ filename — the one- to eight-character first name of a file or group of files. 

■ filetype — the optional one- to three-character category name of a file or group 
of files. If the filetype is present, a period must separate it from the filename. 

■ password— the optional one- to eight-character password which allows you 
to protect your files. It follows the filetype, or the filename if no filetype is 
assigned, and is preceded by a semicolon. 

If you do not include a drive specifier, CP/M 3 automatically uses the default drive. 
If you omit the period and the filetype, CP/M 3 automatically includes a filetype of 
three blanks. 



i DIGITAL RESEARCH" 



S.l Let's Get Past the Foraialides CP/M 3 User's Guide — 

This general form is called a file specification. A file specification names a particu- 
lar file or group of files in the directory of the on-line disk given by the drive 
specifier. For example, 

BsMYFILE.DftT — 

is a file specification that indicates drive B:, filename MYFILE, and filetype DAT. File 
specification is abbreviated to __ 

filespec 

in the command syntax statements. "" 

Some CP/M 3 commands accept wildcards in the filename and filetype parts of the 
command tail. For example, — 



is a file specification with drive specifier B:, filename MY*, and filetype A??. This 
ambiguous file specification might match several files in the directory. 

Put together, the parts of a file specification are represented like this: 

d: filename. typ;password 

In the preceding form, d: represents the optional drive specifier, filename represents 
the one- to eight- character filename, and typ represents the optional one- to three- 
character filetype. The syntax descriptions in this section use the term filespec to 
indicate any valid combination of the elements included in the file specification. The 
following list shows valid combinations of the elements of a CP/M 3 file specification. 

■ filename 

■ filename. typ 

■ filename;password 

■ filename. typipassword 

■ d:filename 

■ d:filename.typ 

■ d:filename;password 

■ d: filename. typ ;pass word 



CP/M 3 User's Guide 



5.1 Let's Get Past the Formalities 



The characters in Table 5-1 have special meaning in CP/M 3, so do not use these 
n characters in file specifications except as Indicated, 



Table 5-1. Reserved Characters 



Character 


1 Meaning 


< = ,!|>tl 
tab space 
carriage return 


file specification delimiters 




drive delimiter in file specification 




filetype delimiter in file specification 


; 


password delimiter in file specification 


• ? 


wildcard characters in an ambiguous file specification 


< > & ! |\ + - 


option list delimiters 


[] 


option list delimiters for global and local options 





delimiters for multiple modifiers inside square brackets 
for options that have modifiers 


/$ 


option delimiters in a command line 


; 


comment delimiter at the beginning of a command line 



m DIGITAL RESEARCH™ 



S.l Let's Get Past the Formalities CP/M 3 User's Guide 

CP/M 3 has already established several file groups. Table 5-2 lists some of their 
filetypes with a short description of each family. Appendix C provides the complete 
list. 





Table 5-2. CP/M 3 Filetypes 


Filetype 


1 Meaning 


ASM 


Assembler source file 


BAS 


CBASIC* source program 


COM 


8080, 8085, or equivalent machine language ptogtam 


HLP 


HELP message file 


SUB 


List of commands to be executed by SUBMIT 


$$$ 


Temporary file 



In some commands, descriptive qualifiers are used with filespecs to further qualify 
the type of fitespec accepted by the commands. For example, wildcard-filespec denotes 
wildcard specifications, dest-filespec denotes a destination filespec, and src-filespec 
denotes a source filespec. 

You now understand command keywords, command tails, control characters, default 
drive, and wildcards. You also see how to use the formal names filespec, drive 
specifier, filename, and filetype. These concepts give you the background necessary to 
compose complete command lines. 



5.2 How Commands Are Described 

CP/M 3 commands appear in alphabetical order. Each command description is 
given in a specific form. This section also describes the notation that indicates the 
optional pans of a command line and other syntax notation. 

■ The description begins with the command keyword in upper-case, 

■ The syntax section gives you one or more general forms to follow when you 
compose the command line. 

'PlDlCITAL RESLARCH'- 



CP/M 3 User's Guide 



5.2 How Commands Are Described 



■ The explanation section defines the general use of the command keyword, 
and points out exceptions and special cases. The explanation sometimes 
includes tables ot lists of options that you can use in the command line. 

■ The examples section lists a number of valid command lines that use the 
command keyword. To clarify examples of interactions between you and the 
operating system, the characters that you enter are slanted. The responses 
that CP/M 3 shows on your screen are in vertical type. 

The notation in the syntax lines describes the general command form using these 
rules: 

■ Words in capital letters must be spelled as shown, but you can use any 
combination of upper- or lower-case letters. 

■ The symbolic notation d:, filename, .typ, ;password, and filespec have the 
general meanings described in Section 5.1. 

■ You must include one or more space characters where a space is shown, 
unless otherwise specified. For example, the PIP options do not need to be 
separated by spaces. 

The following table defines the special symbols and abbreviations used in syntax 
lines. 





Table 5-3. Syntax Notation 




Symbol 


Meaning 




DIR 


Directory attribute. 




n 


You can substitute a number for n. 







Indicates an option or an option list. 




RO 


Read-Only. 




RW 


Read-Write. 




» 


You can substitute a string, which consists ol 
charaaers, for s. 


a group of 



SII DrCITAl, RESEARCH'" 



5.2 How Commands Are Described 



CP/M 3 User's Guide 





Table 5-3. (continued) 


Symbol 1 


Meaning 


SYS 


System attribute. 


{} 


Items within braces are optional. You can enter a command 
without the optional items. The optional itetns add effects to 




your command line. 


[] 


Items in square brackets are options or an option list. If you 
use an option specified within the brackets, you must type the 
brackets to enclose the option. If the right bracket is the last 
character on the command line, it can be omitted. 





Items in parentheses indicate a range of options. If you use a 
range from an option list, you must enclose the range in 
parentheses. 




Ellipses tell you that the previous item can be repeated any 
number of times. 


1 


The or bar separates alternative items in a command line. 
You can selea any or all of the alternatives specified. Mutually 
exclusive options are indicated in additional syntax lines or 
are specifically noted in the text. 


T or CTRL 


Represent the CTRL key on your keyboard. (CTRL charac- 
ters show as ' on your screen.) 


<cr> 


Indicates a carriage return keystroke. 




Wildcard character — replaces all or part of a filename and/or 
filetype. 


? 


Wildcard character — replaces any single character in the same 
position of a filename or filetype. 



a DIGITAL RESEARCH™ 



■■ CP/M 3 User's Guide 5,2 How Commands Are Described 

Let's look at some examples of syntax notation. The CP/M 3 DIR (DlReaory) 

n command displays the names of files cataloged in the disk directory and, optionally, 
displays other information about the files. 

^ The syntax of the DIR command with options shows how to use the command 

I j line syntax notation: 

Syntax: DIR {d:} ) {filespec} {[options]} 

I I optional optional optional 

nThis tells you that the command tail following the command keyword DIR is optional. 
DIR alone is a valid command, but you can include a file specification, or a drive 
specification, or just the options in the command line. Therefore, 

n °"' 

' ' DIR filespec 

DIRd; 
" DIR [RO] 

are valid commands. Funhermore, the drive or file specification can be followed by 
p_ another optional value selected from one of the following list of DIR options; 

' ' RO 

RW 

n !»•' 

! I SYS 

^« Therefore, 

DIR d:filespec [RO] 

I is a valid command. 

Recall that in Section 2 you learned about wildcards in filenames and filetypes. 
n The DIR command accepts wildcards in the file specification. 



W DIGITAL RESEARCH" 



5.2 How Commands Are Described CP/M 3 User's Guide — 

Using this syntax, you can construct several valid command lines: 

DIR 

DIR X.PAS 

DIR X.PAS [RO] ^ 

DIR X.PAS [SYS] ; 

DiR *.PAS 

DIR *.' [RW] 

DIRX.* [DIR] "~ 

The CP/M 3 command PIP (Peripheral Interchange Program) is the file copy pro- 
gram. PIP can copy information from the disk to the screen or printer. PIP can — 
combine two or more files into one longer file. PIP can also rename files after copying 
them. Look at one of the formats of the PIP command line for another example of 
how to use command Lne notation. PIP also copies files from one disk to another _„ 
disk. 

Syntax: PIP dest-filespec — src-filespec{,filespcc...} 

In the preceding example, dest-filespec is further defined as a destination file speci- 
fication or peripheral device (printer, for example) that receives data. Similarly, src- 
filespec is a source file specification or peripheral device (keyboard, for example) that ■— 
transmits data. PIP accepts wildcards in the filename and filetype. (See the PIP com- 
mand for details regarding other capabilities of PIP.) There are, of course, many vaHd 
command lines that come from this syntax. Some examples follow. __ 

PIP NEWFILE,DAT=aLDFILE.DAT 

PIP B:=ft:THISFIL£.DAT 

PIP B:X.BAS=Y.BAS t Z . BAS -^ 

PIP X.BftS=A.BAS, B.BAS, C.BAS 

PIP B:=A:*.BAK 

PIP B!=A!».* -, 

The remainder of this section contains a complete description of each CP/M 3 utility. 
The descriptions are arranged alphabetically for easy reference. 



il DIGITAL RESEARCH™ 



n 



CP/M 3 User's Guide The COPYSYS Command 

The COPYSYS Command 



Syntax: COPYSYS 

Explaoation: The COPYSYS command copies the Cp/M 3 system from a CP/M 3 
system disk to another disk. The disk must have the same format as 
the original system disk. For example, if the system disk is a single- 
density disk, the disk you use to copy onto must also be in single- 
density format. 



The COPYSYS utility copies only the system tracks onto the new disk. 
To use the new disk as a CP/M 3 system disk, you must also copy the 
system file CPM3.SYS to the new disk. COPYSYS gives you the option 
to copy CPM3.SYS to the new disk. To copy other files onto the new 
disk, use the PIP command. 

Example: (^> COPYSYS 

Copvsvs ye r 3.0 

Source drioe nawe (or return for default)C 

Source on C then type return 

Place the disk to be copied in drive C, then enter <cr>. 

Function Complete 

Destination driue name (or return to reboct)C 

Destination on C then type return 

Replace the system disk in C with the new disk, then enter <cr>. 

Function complete 

Do you wish to copy CPM3.SYS?>' 

Source driue name (or return for default)<cr> 

Source on default then type return 

Function complete 

Destination driue name (or return to rebDot)C 

Destination on C then type return 



S DIGITAL RESEARCH'" 



The COPYSYS Command CP/M 3 User's Guide 

Place the disk to be copied in drive C then enter <cr>. 

Funct i on complete 

The preceding example copies the CP/M 3 system using only one disk 
drive C. In the preceding messages, the word source refers to the disk 
that contains the CP/M 3 system, and the word destination refers to 
the disk to which the CP/M 3 system is to be copied. 

The system file CPM3.SYS is copied from the default drive A to the 
new disk in drive C. CP/M 3 requires the file CPM3.SYS to be on the 
system disk. 



n 



CP/M 3 User's Guide The DATE Command 

The DATE Command 

Syntax: DATE {CONTINUOUS} 

DATE {time- specification} 
DATE SET 

Explanation: The DATE command is a transient utility that lets you display and set 
the date and time of day. When you start CP/M 3, the date and time 
are set to the creation date of your CP/M 3 system. Use DATE to 
change this initial value to the current date and time. 



Display Current Date and Time 

Syntax: DATE {CONTINUOUS} 

Ei^lanation: The preceding form of the DATE command displays the current date 
and time. The CONTINUOUS option allows continuous display of the 
date and time. The CONTINUOUS option can be abbreviated to C. 
You can stop the continuous display by pressing any key. 

Examples: fi,>DftTE 
f^>DArE C 

The first example displays the current date and time. A sample display 
might be: 

Fri 08/13/82 03: 15:37 

The second example displays the date and time continuously until you 
press any key to stop the display. 



Set the Date and Time 



Syntax: DATE {time-specification} 

DATE SET 



8 DrCITALRESEAKLH" 



The DATE Command CP/M 3 User's Guide — 

Expianarion: The first form allows the user to enter both date and time in the com- 
mand. The time- specification format is "~ 

MM/DD/YY HH:MM:SS 

where: 

MM is a month value in the range 1 to 12, 

DD is a day value in the range 1 to 31. 

YY is the two-digit year value relative to 1900. 

HH is the hour value in the range of to 23. 

MM is the minute value in the range of to 59. — 

SS is the second value in the range of to 59. 

The system checks the validity of the date and time entry and deter- _ 
mines the day for the date entered. 

The second form prompts you to enter the date and the time. To keep 

the current system date or time, press the carriage return. "^ 

Examples: f\>DATE 0B/ia/8Z 10!30:00 

The system responds with 

Press any ke/ to set time _ 

When the time occurs, press any key. DATE initializes the time at that 
instant, and displays the date and time: 

Sat OG/ia/82 10:30:00 

ti>DATE SET ^ 

The system prompts with 

Enter today 's date (MM/DD/YY) ; ~ 



- e DIGITAL RESEAR( 



CP/M 3 User's Guide The DATE Command 

Press the carriage return to skip or enter the date. Then the system 
prompts with 

Enter the time (HH:MM:SS) : 

Press the carnage return to skip or enter the time and the system prompts 
with 

Press anf Key to set time 

to allow you to set the time exactly. 



S DiClTAL RESEARCH'" 



The DEVICE Command CP/M 3 User's Guide 

The DEVICE Command 

Syntax: DEVICE {NAMES | VALUES | physical-dev | logical-dev} 

DEVICE logical-dev = physical-dev {option} 

{,physical-dev {option},.--} 
DEVICE logical-dev = NULL 
DEVICE physical-dev {option} 
DEVICE CONSOLE [PAGE | COLUMNS = columns | LINES -lines} 

Explanation: The DEVICE command is a transient utility that displays current 
assignments of CP/M 3 logical devices and the names of physical devices. 
DEVICE allows you to assign logical CP/M 3 devices to peripheral 
devices attached to the computer. The DEVICE command also sets the 
communications protocol and speed of a peripheral device, and dis- 
plays or sets the current console screen size. 

CP/M 3 supports the following five logical devices: 

CONIN: 

CONOUT: 

AUXIN: 

AUXOUT: 

LST: 

These logical devices arc also known by the following names: 

CON: (for CONIN: and CONOUT:) 
CONSOLE: (for CONIN: and CONOUT:) 
KEYBOARD (for CONIN:) 
AUX: (for AUXIN: and AUXOUT:) 
AUXILIARY: (for AUXIN: and AUXOUT:) 
PRINTER (for LST:) 

The physical device names on a computer vary from system to system. 
You can use the DEVICE command to display the names and attributes 
of the physical devices that your system accepts. 



- m DIGITAL RESEARCH" 



CP/M 3 User's Guide The DEVICE Command 

Display Device Characteristics and Assignments 

Syntax: DEVICE { NAMES 1 VALUES 1 physical-dev | logical-dcv} 

Explanation: The preceding form of the DEVICE command displays the names and 
attributes of the physical devices and the current assignments of the 
logical devices in the system. 

Examples: P>>DEIJICE 

The preceding command displays the physical devices and current 
assignments of the logical devices in the system. The following is a 
sample response: 



I = Ir-.'u 


.a = DutPut >S>S>rlil >X>)(on- 


off 






CRT 


3E00 105 


LPT 3600 


10SX 


CRTl 


9600 


CRTZ 


9600 lOS 


CRT3 leoo 


IDS 


LPTl 


13d 


CEN 


NONE 


WODEMl 19Z00 


I OS 


MODEMS 


300 


CTRLRl 


150 


GRftCRT 19200 


IDS 


DlflBLD 


110 


CTRLRZ 


300 


SCBTY 7200 








Currtn 
CDNIN: 


= CRT 










CONOUT 


= CRT 










AUXINi 


- NullDtu 


ICC 








flUKOUT 


• Null Diu 


let 









The system prompts for a new device assignment. You can enter any 
valid device assignment [as described in the next section). If you do not 
want to change any device assignments, press the RETURN key. 

P,>DEVICE NAMES 

The preceding command lists the physical devices with a summary of 
the device characteristics. 



Ssl DIGITAL RESEARCH" 



The DEVICE Command CP/M 3 User's Guide 

tODEKiICE VALUES 

The preceding command displays the current logical device assignments. 

f\>DEVICE CRT 

The preceding command displays the attributes of the physical device 
CRT. 

A>DFV ICE CON 

The preceding command displays the assignment of the logical device 
CON: 



Assign a Logical Device 

Syntax: DEVICE logical-dev = physical-dev {option} 

{,physical-dev {option},,..} 
DEVICE logical-dev - NULL 

Explanation: The first form assigns a logical device to one or more physical devices. 
The second form disconnects the logical device from any physical device. 



- m DIGITAL RESEARCH" 



CP/M 3 User's Guide 



The DEVICE Command 



Table S-4. DEVICE Oprioi 



Option 



Meaning 



refers to the XON/XOFF communications protocol. 
This protocol uses two special characters in the ASCII 
character set called XON and XOFF. XON signals 
transmission on, and XOFF signals transmission off. 
Before each character is output from the computer to 
the peripheral device, the computer checks to see if 
there is any incoming data from the peripheral. If the 
incoming character is XOFF, the computer suspends 
all further output until it receives an XON from the 
device, indicating that the device is again ready to 
receive more data. 

indicates no protocol and the computer sends data to 
the device whether or not the device is ready to receive 



is the speed of the device. The system accepts the 
following baud rates: 



50 75 

150 300 

1800 2400 

7200 9600 



110 
600 
3600 

19200 



134 
1200 
4800 



Examples: 



f^>DEVICE CONOUTs'LPT ,CRT 
Pi>DEVICE AUXIN:=CRT2 LXON >36003 
f\>DE'JICE LSTs=NULL 



The first example assigns the system console output, CONOUT;, to the 
printer, LPT, and the screen, CRT. The second example assigns the 
auxiliary logical input device, AUXIN:, to the physical device CRT 
using protocol XON/XOFF and sets the transmission rate for the device 
at 9600. The third example disconnects the list output logical device, 
LST:. 



m DIGITAL RESEARCH'" 



The DEVICE Command 



CP/M 3 User's Guide 



s the attributes of the 



Set Attributes of a Physical Device 

Syntax: DEVICE physical-dev {option} 

Explanation: The preceding form of the DEVICE command s 
physical device specified in the command. 

Example: fi>D£VICE LPT [X0N,3G00J 

The preceding command sets the XON/XOFF protocol for the physical 
device LPT and sets the transmission speed at 9600, 

Display or Set the Current Console Screen Size 

Syntax: DEVICE CONSOLE [PAGE | COLUMNS = columns | LINES = hnes] 

Explanation: The preceding form of the DEVICE command displays or sets the cur- 
rent console size. 

Examples: A>0£'l'ICf CONSOLE CPftGEl 

(^> DEVICE CONSOLE CCOLUMNS = aO , LINES=1G1 

The first example displays the current console page width in columns 
and length in lines. The second example sets the screen size to 40 
columns and 16 lines. 



- m DIGITAL RESEARCH™ 



n 



CP/M 3 User's Guide The DIR Command 

The DIR Command 



Syntax: DIR {d:} 

DIR {filespec} 

DIRSYS id:} 
DIRSYS {filespec} 

DIR {d:} [options] 

DIR {filespec} {filespec}... [options] 

Explanation: The DIR command displays the names of files and the attributes asso- 
ciated with the files. DIR and DIRSYS are built-in utihties; DIR with 
options is a transient utility. 

Display Directory 

Syntax: DIR {d:} 

DIR {filespec} 

DIRSYS {d;} 
DIRSYS {filespec} 

Explanation: The DIR and DIRSYS commands display the names of files cataloged 
in the directory of an on-line disk. The DIR command lists the names 
of files in the current user number that have the Directory (DIR) attri- 
bute. DIR accepts wildcards in the file specification. You can abbreviate 
the DIRSYS command to DIRS. 

The DIRSYS command displays the names of files in the current user 
number that have the System (SYS) attribute. Although you can read 
System (SYS) files that are stored in user from any other user number 
on the same drive, DIRSYS only displays user files if the current user 
number is 0. DIRSYS accepts wildcards in the file specification. 

If you omit the drive and file specifications, the DIR command displays 
the names of all files with the DIR attribute on the default drive for the 
t user number. Similarly, DIRSYS displays all the SYS files. 



i DIGITAL RESEARCH- 



The DIR Command CP/M 3 User's Guide — 

If the drive specifier is included, but the filename and filetype are omit- 
ted, the DIR command displays the names of all DIR files in the current 
user on the disk in the specified drive. DIRSYS displays the SYS files. 

If the file specification contains wildcard characters, all filenames that — 
satisfy the match are displayed on the screen. 

If no filenames match the file specification, or if no files are cataloged ^ 
in the directory of the disk in the named drive, the DIR or DIRSYS 
command displays the message: 

No File "" 

If system (SYS) files match the file specification, DIR displays the message: 

SYSTEM FILE(S> EXIST 

If nonsystem (DIR) files match the file specification, DIRSYS displays 
the message: 

NON-SYSTEM FILES(S) EXIST 

The DIR command pauses after filling the screen. Press any key to 
continue the display. 

Note: You can use the DEVICE command to change the number of 
columns displayed by DIR or DIRSYS. 

Examples: P\>DIR ~ 

Displays all DIR files cataloged in user on the default drive A. 

A>D/ff Bi 

Displays all DIR files for user on drive B. 

f\>DIR B:X.Bfi5 

Displays the name X.BAS if the file X.BAS is present on drive B. — 

im DIGITAL RESEARCH'" 



CP/M 3 User's Guide The DIR Command 

Displays all DIR files with filetype BAS for user 4 on drive A. 

B>DIR ft:H*.C?D 

Displays all DIR files for user on drive A whose filename begins with 
the letter X, and whose three character filetype contains the first char- 
acter C and last charaacr D, 



Displays all files for user on drive A that have the system (SYS) 
attribute. 

3A>DJ/?S *,COM 

This abbreviated form of the DIRSYS command displays all SYS files 
with filetype COM on the default drive A for user 3. 



Display Directory with Options 

Syntax: DIR {d:} [options] 

DIR {filespec} {filespec}.,.[ options] 

Explanation: The DIR command with options is an enhanced version of the DIR 
command. The DIR command displays CP/M 3 files in a variety of 
ways. DIR can search for files on any or all drives, for any or all user 
numbers. 

DIR allows the option list to occur anywhere in the command tail. 
These options modify the entire command line. Only one option list is 
allowed. 

Options must be enclosed in square brackets. The options can be used 
individually, or strung together separated by commas or spaces. Options 
can be abbreviated to only one or two letters if the abbreviation unam- 
biguously identifies the option. 



I DIGITAL RESEARCH'" - 



The DIR Command 



CP/M 3 User's Guide 



If a directory lisring exceeds the size of your screen, DIR automatically 
halts the display when it fills the screen. Press any key to continue the 
display. 



Table 5-5. DIR Display Options 



Option 




Function 


ATT 




displays the user-definable file attributes Fl, F2, 
F3, and F4. 


DATE 




displays files with date and time stamps. Jf date 
and time stamping is not active, DIR displays the 
message: 

Date and Time Stamping Inactive, 


DIR 




displays only files that have the DIR attribute. 


DRIVE- 


-ALL 


displays files on all accessed drives. DISK is also 
acceptable in place of DRIVE in all the DRIVE 
options. 


DRIVE = 


= (A,B,C, 


■,P) 
displays files on the drives specified. 


DRIVE 


= d 


displays files on the drive specified by d. 



- m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



The DIR Command 



Tabic 5-5. (continued) 



Option 



displays the files on the default drive and user 
area that do not match the files specified in the 
command line. 



sends an initial form-feed to the printer device if 
the printer has been activated by CTRL -P. If the 
LENGTH = n option is also specified, DIR issues 
a form-feed every n lines. Otherwise, the FF option 
deactivates the default paged output display. 



shows the name of the file and the size of the file. 
The size is shown as the amount of space in ki- 
lobytes and the number of 128-byte records allo- 
cated to the file. FULL also shows the attributes 
the file. (See the SET command for description of 
file attributes). If there is a directory label on the 
drive, DIR shows the password protection mode 
and the time stamps. The display is alphabetically 
sorted. FULL is the default output format for dis- 
play when using DiR with options. 



displays n hnes of output before inserting a table 
heading, n must be in the range between 5 and 
65536. The default length is one full screen of 
information. 



The DIR Command 



CP/M 3 User's Guide 





Tabic 5-S. (continued) 


Option 


Function 


MESSAGE 






displays the names of the specified drives and user 
numbers it is currently searching. If there are no 
files in the specified locations, DIR displays the 
file not found message. 


NOPAGE 






continuously scrolls information by on the screen. 
Does not wait for you to press a key to restart 
the scrolling movement. 


NOSORT 






displays files in the order it finds them on the 
disk. If this option is not included, DIR displays 
the files alphabetically. 


RO 






displays only the files that have the Read-Only 
attribute. 


RW 






displays only the files that are set to Read-Write. 


SIZE 






displays the filename and file size in kilobytes. 


SYS 






displays only the files that have the SYS attribute. 



- II DIGITAL RESEARCH- 



CP/M 3 User's Guide 



The DIR Comniand 



Table 5-5. (continued) 



Option 




Function 


USER = ALL 




displays all files under all the user numbers for 
the default drive. 


USER = n 




displays the files under the user number specified 
by„. 


USER = (0,1,. 


,15 


displays files under the user numbers specified. 



Examples: 



f\>DIR Ci IFULLJ 
P\>DIRCl CSIZEJ 



The following is sample output of the [FULL] option display format 
shown in the first example of the DIR command; 



DITS 


BAK 




DITS 


TES 




DITS 


y 




DITS 


ZZ 




SETDEF 


COM 




SUBMIT 


TXZ 




SUBMIT 


TXl 





09/01/az i3!0a 

09/01/82 13i07 
0a/Z5/eZ 03:33 
0B/£5/az 03!3B 



09/01/82 13:07 

09/01/82 13i09 

OS/25/82 03:33 

OB/25/82 03:36 

08/25/82 03:3G 



a DIGITAL RESEARCH- 



The DIR Command CP/M 3 User's Guide 

The following is sample output of the [SIZE] option display format 
shown in the second example of the DIR command: 



C; 


DITS 


BAK 


IK 


! DITS 


TES 


IK ! DITS 


C: 


DITS 


ZZ 


IK 


1 SETDEF 


COH ' 


]K i SUBMIT 


Ci 


SUBMIT 


TXl 


5K 


! 







Both the full format and the size format follow their display with two 
lines of totals. The first line displays the total number of kilobytes, the 
total number of records, and the total number of files for that drive 
and user area. The second line displays the total number of IK blocks 
needed to store the listed files. The number of IK blocks shows the 
amount of storage needed to store the files on a single density disk, or 
on any drive that has a block size of one kilobyte. The second line also 
shows the number of directory entries used per number of direaory 
entries available on the drive. 

A>DJ/? CDRIiJE'CfFFJ 

DIR sends a form-feed to the printer before displaying the files on 
drive C. 

ft>DIR D: LRUtSYSJ 

The preceding example displays alt the files on drive D with Read- 
Write and SYS attributes. 

fl>D7ff C: [USER=ftLL3 

Displays all the files under each user number (0-15) on drive C. 

ft>DJ"ff CUSER = ZJ 

Displays all the files under user 2 on the default drive. 



HI DIGITAL RESEARCH™ 



CP/M 3 User's Guide The DIR Command 



fi>£JJff C; [USER=(3*atlO)J 

This example displays all the files under user numbers 3, 4, and 10 on 
drive C. 

A>DIff CDfti"V£=flLLJ 

Displays all the files under user on all the drives in the drive search 
chain. (See the SETDEF command.) 

aayoiR [drive=cj 

Displays all the files under user 4 on drive C. 

A>D7/? [DRIUE=(B,D}J 

Displays all the files under user on drives B and D. 

f\>DIR CexcludeJ it.COM 

The preceding example above lists all the files on the default drive and 
user that do not have a filetype of COM. 

f\>DIR [user = all idrive^al I isrsl *,PLI *.COM *,fiiSM 

The preceding command line instructs DIR to list all the system files of 
type PLI, COM, and ASM on the system in the currently active drives 
for all the user numbers on the drives. 

A>0:/? X.SUB [MESSAGE ,USER=ALL ,DRIVE=ALL J 

The preceding command searches all drives under each user number for 
X.SUB. During the search, DIR displays the drives and user numbers. 

A>DJff i:drive = all usBr = allJ TBSTFILE.BOB 

The preceding example instructs DIR to display the filename 
TESTFILE.BOB if it is found on any logged-in drive for any user number. 



P DIGITAL RESEARCH'" - 



The DIR Command CP/M 3 User's Guide — 



A>DIff [size ,rwJD! 

The preceding example instructs DIR to list each Read-Write file that 
resides on drive D with its size in kilobytes. Note that D: is equivalent 
loD:*.*. 



- m DIGITAL RESEARCH" 



pi CP/M 3 User's Guide The DUMP Command 

The DUMP Command 

n 

Syntax: DUMP filespec 

n Explanation: Dump displays the contents of a file in hexadecimal and ASCII format. 

Example: A >Dt;rtP ABC . TEX 
' I Console output can look like the following: 

DUMP - Uiriion 3,0 

nOOOOi dl 92 as OD OA it 05 dS OD OA 07 OB 05 OD OA lA ABC . .OEF. .GHI , . . . 
0010; lA lA lA lA lA lA lA lA lA lA lA lA lA lA lA lA 



RESEARCH" 



The ED Command CP/M 3 User's Guide 

The ED Command 

Syntax: ED {input-file spec {d: | output-filespec}} 

Explanation: The ED transient utility lets you create and edit a disk file. 

The ED utility is a line-oriented context editor. This means that you 
create and change character files line-by-line, or by referencing individual 
characters within a line. 

The ED utility lets you create or alter the file named in the file specifi- 
cation. Refer to Section 6 for a description of the ED utility. 

The ED utility uses a portion of your user memory as the active text 
buffer where you add, delete, or alter the characters in the file. You use 
the A command to read all or a portion of the file into the buffer. You 
use the W or E command to write all or a portion of the characters from 
the buffer back to the file. 

An imaginary charaaer pointer, called CP, is at the beginning of the 
buffer, between two characters in the buffer, or at the end of the buffer. 

You interact with the ED utility in either command or insert mode. ED 
displays the * prompt on the screen when ED is in command mode. When 
the * appears, you can enter the single letter command that reads text 
from the buffer, moves the CP, ot changes the ED mode of operation. 
When in command mode, you can use the line-editing characters CTRL- 
C, CTRL-E, CTRL-H, CTRL-U, CTRL-X, and RUBOUT to edit your 
input. In insert mode, however, you use only CTRL-H, CTRL-U, CTRL- 
X, and RUBOUT. 



S DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



The ED Command 



Table 5-6. ED Command Summary 



Command Action 



Append n lines from original file to memory 
buffer. 



Append file until buffer is one half full. 



Append file until buffer is full (or end of file). 



Move CP to beginning (B) or bottom (-B) of 
buffer. 



Move CP n characters forward (C) or back (-C) 
through buffer. 



Delete n characters before (-D) or from (D) the 

CP. 



Save new file and return to CP/M 3. 



Fst rins-C TZ> 



Find charaaer string. 



1 DIGITAL RESEARCH'- 



TTie ED Command 



CP/M 3 User's Guide 



Tabic 5-6. (continued) 



Command Action 



Save the new file, then reedit, using the new file 
as the original file. 



Enter insert mode; use t Z or ESCape to exit 
insert mode. 



1st rin3< TZ> 



Insert string at CP. 



Note: upper-case 1 forces all input to upper-case; while iower-case 
i allows upper- and lower-case. 



Jsearoh_str*Zins_str''Zdel_to_str-CTH} 
Juxtapose strings. 



Delete (kill) n lines from the CP. 



nL . -nL , OL 



Move CP n lines. 



iMCDMMands 



Execute commands n t 



Move CP n lines and display that line. 



S DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



The ED Command 



Table 5-6. (continued) 



Command 


Action 


n: 


Move to line n. 


incommand 






Execute command through line n. 


Nstrins«tZ> 






Extended find string. 


a 






Return to original file. 


nP, -nP 






Move CP n lines forward and display n hnes at 




console. 


Q 






Abandon new file, return to CP/M 3. 


R{;z> 






Read X$$$$$$S.LIB file into buffer. 


RfilespectT 


Z> 




Read filespec into buffer. 


Sdelete st n 


n9- Zinsert st rin3<:Z> 




Substitute string. 



i DIGITAL RESEARCH'" - 



The ED Command 



CP/M 3 User's Guide — 





Table S-6. (continued} 


Command 


Action 


v,J, -T,J, OT 






Type n lines. 


U t -U 






Upper-case translation. 


y . -u, oy 






Line numbering on/off, display free buffer space. 


nU 






Write n lines to updated file. 


nx-c:z> 






Write or append n lines to X$$S$S$S.LIB. 


nXf ilespec-( 


Z> 




Write n lines to filespec or append if previous x 
command applied to the same file. 


ox-t rz> 






Delete file X$$$S$$$.LIB. 


OXf ilespeci 


Z> 




Delete filespec. 


nZ 






Wait n seconds. 



M DIGITAL RESEARCH'" 



CP/M 3 User's Guide The ED Command 

Section 6 gives a detailed description of the overall operation of the ED 

utility and the use of each command. 

If you do not include a command tail in the ED command, it prompts 
you for the input filespec and the output filespec as follows; 

Enter Input File: 

After you enter the input filespec, ED prompts again; 

Ente r Output File: 

Enter a filename or drive if you want the output file or its location to 

be different from that of the input file. Press RETURN if you want the 
output file to replace the input file. In this case, the input file is renamed 
to type BAK. 

If the second file specification contains only the drive specifier, the 
second filename and filetype become the same as the first filename and 
filetypc. 

If the file given by the first file specification is not present, ED 
the file and writes the message: 



If the file given by the first filespec is already present, you must 
the A command to read portions of the file to the buffer. If the s 
the file does not exceed the size of the buffer, the command 



reads the entire file to the buffer. 

The i {Insert) command places ED in insert mode. In this mode, any 
characters you type are stored in sequence in the buffer starting at the 
current CP. 



m DIGITAL RESEARCH"' 



The ED Command CP/M 3 User's Guide 

Any single letter commands typed in insert mode are not interpreted as 
commands, but are simply stored in the buffer. To return from insert 
mode to command mode, press CTRL-Z or the ESC key. Note that 
you can always substitute the ESC key for CTRL-Z in ED. 

The single letter commands are usually typed in lower-case. The com- 
mands that must be followed by a character sequence end with CTRL- 
Z if they are to be followed by another command letter. 

Any single letter command typed in upper-case tells ED to internally 
translate to upper-case all characters up to the CTRL-Z that ends the 
command. 

When enabled, line numbers that appear on the left of the screen take 
the form: 



where nnnnn is a number in the range I through 65535. Line numbers 
are displayed for your reference and are not contained in either the 
buffer or the character file. The screen line starts with 



when the CP is at the beginning or end of the buffer. 

Examples: A>ED tlYPROG.PftS 

If not already present, this command line creates the file MYPROG.PAS 
on drive A. The command prompt 



appears on the screen. This tells you that the CP is at the beginning of 
the buffer. If the file is already present, issue the command 

• *«a 

to fill the buffer. Then type the command 

t*Of 

la DIGITAL RESEARCH" 



CP/M 3 User's Guide The ED Command 

to fill the screen with the first n lines of the buffer, where n is the 
current default page size (See the DEVICE command to set the page 

size). 

Type the command 



to stop the ED utility when you are finished changing the charaaer file. 
The ED utility leaves the original file unchanged as MYPROG.BAK 
and the altered file as MYPROG.PAS. 

A>£D MYPROCPftS B sNBUPROG . POS 

The original file is MYPROG.PAS on the default drive A. The original 
file remains unchanged when the ED utility finishes, with the altered 
file stored as NEWPROG.PAS on drive B. 

F\>BsED MYPROG.PftS B: 

The ED.COM file must be on drive B. The origina! file is MYPROG.PAS 
located on drive A, It remains unchanged, with the altered program 
stored on drive B as MYPROG.PAS. 



S DIGITAL REStARCH" 



The ERASE Command CP/M 3 User's Guide -^ 

The ERASE Command __ 

Syntax: ERASE {filespec} {[CONFIRM]} 

Explanation: The ERASE command removes one or more files from a disk's direc- 
tory in the current user number. Wildcard characters are accepted in 
the filespec. Directory and data space are automatically reclaimed for 
later use by another file. The ERASE command can be abbreviated to ~ 
ERA. 

Use the ERASE command with care because all files in the current user — 
number that satisfy the file specification are removed from the disk 
directory. 

Command lines that take the form 

ERASE {d:}wildcard-filespec 

require your confirmation because they erase an entire group of files, 
not just one file. The system prompts with the following message: 

ERASE <d!>wildcard-filespeo (Y/N)? 

Respond with y if you want to remove all matching files, and n if you 
want to avoid erasing any files. 

If no files match the file specification, you see the following message: 

No File 

The CONFIRM option informs the system to prompt for verification _ 
before erasing each file that matches the filespec. You can abbreviate 
CONFIRM to C. 

If you use the CONFIRM option with wildcard-filespec, then ERASE "~ 
prompts for confirmation for each file. You can seleaively erase the 
files you want by responding Y to the confirm message, or keep the 
files by responding N to the confirm message. _ 



- SI DICITAI, RESEARCH'- 



CP/M 3 User's Guide 
Examples: 



The ERASE Command 



fi>£"ffflSEX.PflS 

This command removes the file X.PAS from the disk in drive A. 

ft>f/?fl *.PRN 

The system asks to confirm: 

ERASE t.PRN (Y/N)?y 

All files with the filetype PRN are removed from the disk in drive A. 

b>ERfi A.-MY*.* [CONFIRM] 

Each file on drive A with a filename that begins with MY is displayed 
with a question mark for confirmation. Type Y to erase the file dis- 
played, N to keep the file. 

fi > ERA 5 : * . * 

ERASE B;*.* ( Y/N)?/ 

All files on drive B are removed from the disk. 



a DIC;lTAL RESEARCH™ 



The GENCOM Command CP/M 3 User's Guide 

The GENCOM Command 



Syntax: GENCOM {COM-filespec} {RSX-filespec}... 

{[LOADER|NULL|SCB - {offset, value)] J 

Explanation: The GENCOM command is a transient utility that creates a special 
COM file with attached RSX files. RSX files are used as Resident Sys- 
tem Extensions and are discussed in detail in the CP/M Plus (CP/M 
Version 3) Operating System Programmer's Guide. GENCOM places a 
special header at the beginning of the output program file to indicate 
to the system that RSX loading is required. It can also set a flag to 
keep the program loader active. 

The GENCOM command can also restore a file already processed by 
GENCOM to the original COM file without the header and RSXs. 
GENCOM has three options that help you attach RSX files: 

■ The LOADER option sets a flag to keep the program loader active. 
(For complete details on the LOADER option read about CP/M 
function 59 in the CP/M Plus (CP/M Version 3) Operating System 
Programmer's Guide.) This option is used only if no RSX files are 
attached to the COM file. 

■ The NULL option indicates that only RSX files are specified. 
GENCOM creates a dummy COM file for the RSX files. The output 
COM filename is taken from the filename of the first RSX-filespec. 

■ The SCB = (offsetjvalue) option sets the System Control Block from 
the program by using the hex values specified by (offset,value). For 
complete details on the SCB option read about CP/M function 49 in 
the CP/M Plus (CP/M Version 3) Operating System Programmer's 
Guide. 



Attach RSX Files to a COM File 

Syntax: GENCOM COM-filespec RSX-filespec... 

{[LOADERlSCB = [offsct,value)]} 



- m niGlTAL RESEARCH™ 



-^ CP/M 3 User's Guide The GENCOM Command 

Explanation: The preceding form of the GENCOM command creates a COM file 

nwith a header and attached RSXs. A maximum of 15 RSXs can be 
attached. GENCOM expects the first filespec to be a COM file and the 
following filespecs to be RSX files. Note that the original COM file is 
_ replaced by the newly-created COM file. 

'' Example: Pi>GENCOM NYPROG PROGl PR0G2 

n The preceding command generates a new COM file MYPROG.COM 

I with attached RSXs PROGl and PROG2. 

" Generate a COM File Using only RSX Files 

Syntax: GENCOM RSX-filespec {RSX-filespec}... 

M [NULL {SCB = {offsct,value)}] 

Explanation: The preceding form of the GENCOM command anaches the RSX files 
n to a dummy COM file. GENCOM creates a COM file with the fik- 

) j name of the first RSX-filespec in the command tail. This format allows 

the system to load RSXs directly. 

I I Example: f\>GENCOM PROGl PR0G2 [NULL] 

The preceding command creates a COM file PROGl.COM with Resi- 
n dent System Extensions PROGl .RSX and PROG2.RSX. 



Restore a File with Attached RSXs to Original COM File 

Syntax: GENCOM filename 

Explanation: The preceding form of the GENCOM file takes a file that has already 
been processed by GENCOM and restores it to its original COM file 
format. This form of the command assumes a filetype of COM. 

Example: fl > GENCOM MY PROG 

In the preceding command, GENCOM takes MYPROG.COM, strips 
off the header and deletes all attached RSXs to restore it to its original 
COM format. 

m DICrTAL RESEARCH" 



The GENCOM Command CP/M 3 User's Guide 

Update (Add or Replace) RSX FUes 

Syntax: GENCOM COM-filespec RSX-filespec... 

{[LOADER 1 SCB = (offset,value)l} 

Explanation: The preceding form of the GENCOM command adds and/or replaces 
RSX files to a file already processed by GENCOM. 

GENCOM inspects the list of RSX files. If they are new, they are added 
to the file already processed by GENCOM, If they already exist, then 
GENCOM replaces the existing RSXs with the new RSX files. 

Example: Pi>GENCOM MYPROG PROGl PROGZ 

In the preceding example, GENCOM looks at MYPROG.COM, which 
is already processed by GENCOM, to see if PROGl.RSX and 
PROG2.RSX are already attached RSX files in the module. If either 
one is already attached, GENCOM replaces it with the new RSX mod- 
ule. Otherwise, GENCOM appends the specified RSX files to the COM 
file. 



Attach a Header Record 

Syntax: GENCOM filename [SCB = (offsct,value),... | LOADER] 

Explanation: The preceding syntax line attaches a GENCOM header record, with 
the SCB or loader flag set, to a file of type COM that contains no 
RSXs. This form of the command does not attach RSXs to a file. 



il DIGITAL RESEARCH'- 



CP/M 3 User's Guide The GENCOM Command 



Examples: ft>GENCDM FILETUO CloaderJ 

The preceding command attaches a 256-byte header record to the file 
FlLETWO.COM and sets the loader flag in the header record. 

Pi>GBNCDM FILEFOUR [sct=(l ,1 )1 

The preceding command causes the program loader to set byte I of the 
System Control Block to 1 when it loads FILEFOUR.COM. 

For more information, see functions 49, Set/Get System Control Block, 
and 59, Load Overlay or Resident System Extensions, in the CP/M Plus 
(CP/M Version 3) Operating System Programmer's Guide. 



m DIGITAL RESEARCH™ 



TTie GET Command CP/M 3 User's Guide — 

The GET Command 

Syntax: GET {CONSOLE INPUT FROM} FILE filespec 

{[{ECHO [NO ECHO}|SYSTEM]} 
GET {CONSOLE INPUT FROM} CONSOLE " 

Explanarion: The GET command is a transient utility that direas CP/M 3 to take 

console input from a file. The file can contain CP/M 3 system com- — 
mands and/or input for a user program. If you use the SYSTEM option, 
GET immediately takes the next system command from the file. 

Console input is taken from a file until the program tctminates. If the 
file is exhausted before program input is terminated, the program looks 
for subsequent input from the console. If the program terminates before 
exhausting all its input, the system reverts back to the console for "" 
console input. 

\fhen the SYSTEM option is used, the system immediately goes to the — 
file specified for console input. If you omit the SYSTEM option, you 
can enter one system command to initiate a user program whose con- 
sole input is taken from the file specified in the GET command. The _ 
system reverts to the console for input when it reaches the end of the 
GET file input. The system also reverts to the console for console input 
if a GET CONSOLE INPUT FROM CONSOLE command is included 
in the input file. -" 

Get Console Input from a File „ 

Syntax: GET {CONSOLE INPUT FROM} FILE filespec {[options]} 

Explanation; The preceding form of the GET command tells the system to get sub- "" 
sequent console input from a file. Table 5-7 lists the GET options that 
you use in the following format: 

[{ECHO I NO ECHO} | SYSTEM] 



a DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



The GET Command 



Tabic 5-7. GET Opdons 



Option 



Meaning 



specifies that the input is echoed to the console. 
This is the default option. 

specifies that the file input is not to be echoed to 
the console, The program output and the system 
prompts are not affected by this option and are 
still echoed to the console, 

specifies that all system input is to be taken from 
the disk file specified in the command line. GET 
takes system and program input from the file until 
the file is exhausted or until GET reads a GET 
console command from the file. 



Examples; 



f\> GET FILE X INPUT 
P>>MYPROC 



The preceding sequence of commands tells the system to activate the 
GET utility. However, because SYSTEM is not specified, the system 
reads the next input hne from the console and executes MYPROG. If 
MYPROG program requires console input, it is taken from the file 
XINPUT. When MYPROG terminates, the system reverts to the con- 
sole for console input. 

fl>G£'7" FILE XIN2 [SYSTFMJ 

The preceding command immediately direas the system to get subse- 
quent console input from file XIN2 because it includes the SYSTEM 
option. The system reverts to the console for console input when it 
reaches the end of file in XIN2. Or, XIN2 can redirect the system back 
to the console if it contains a GET CONSOLE command. 



B DIGITAL RESEARCH™ 



The GET Command CP/M 3 User's Guide _ 

Terminate Console Input &om a File 

Syntax: GET {CONSOLE INPUT FROM} CONSOLE 

Expianadon: The preceding form of the GET command tells the system to get con- _ 
sole input from the console. 

Example: f\>GEr CONSOLE 

The preceding GET command tells the system to get console input from 
the console. You can use this command in a file (previously specified in 
a GET FILE command) which is already being read by the system for ~m 
console input. It is used to redirect the console input to the console 
before the end of the file is reached. 



m DIGITAL RESEARCH™ 



n 



CP/M 3 User's Guide The HELP Command 

The HELP Command 

Syntax: HELP {topicHsubtopicl subtopic2...subtopic8H[NO PAGEjLIST]} 

HELP [EXTRACT] 
HELP [CREATE] 

Explanation: The HELP command is a transient utility that provides summarized 
information for all of the CP/M 3 commands described in this manual, 
in the distributed CP/M 3 system, HELP presents general information 
on a command as a topic and detailed information on a command as a 
subtopic. HELP with no command tail displays a list of all the available 
topics, HELP with a topic in the command tail displays information 
about that topic, followed by any available subtopics. HELP with a 
topic and a subtopic displays information about the specific subtopic. 

After HELP displays the information for your specified topic, it displays 
the special prompt HELP> on your screen. Subtopics can be accessed 
by preceding the subtopic with a period. The period causes the subtopic 
search to begin at the last known level. You can continue to specify 
topics for additional information, or simply press the RETURN key to 
return to the CP/M 3 system prompt. 

You can abbreviate the names of topics and subtopics. Usually one or 
two letters is enough to specifically identify the topics. 

Display Information 

Syntax: HELP topic {subtopic l...subtopic8K [NO PAGEiLIST]} 

HELP>.Subiopic 

Explanation: The preceding forms of the HELP command display the information 
for the specified topic and subtopics. Use the following two options 
with this form of the HELP command: 

■ The NOPAGE option disables the default paged display of every n 
lines, where n is the number of lines per page as set by the system or 
as set by the user. To stop the display, press CTRL-S. To resume the 
display, press CTRL-Q. You can abbreviate NOPAGE to N. (See the 
DEVICE command for more information about setting the number 
of lines per page.) 

m DIGITAL RESEARCH'" 



The HELP Command CP/M 3 User's Guide 

■ The LIST option is the same as NOPAGE, except that it eliminates 
extra lines between headings. Use this option with CTRL-P to list 
the help information on the printer. 

Examples: fl>H£LP 

The preceding command displays a list of topics for which help is 

available. 

fii>HELP DATE 

This command displays general information about the DATE com- 
mand. It also displays any available subtopics. 

f>,>HELP DIR OPTIONS [NJ 

The preceding command includes the subtopic options. In response, 
HELP displays information about options associated with the DIR 
command. The display is not in paged mode. 



The preceding command displays general information about the ED 
utility. 

t\>HELP ED COMMfiNDS 

This form of HELP displays information about commands internal to 
ED. The preceding example can also be entered as 

f>i>HELP ED 
HELPy .COMMANDS 



Add Your Own Descriptions to the HELP.HLP File 

Syntax: HELP [EXTRACT] 

HELP [CREATE] 



- m DIGfTAl, RESEARCH™ 



CP/M 3 User's Guide The HELP Command 

Explanarion: CP/M 3 is distributed with two related HELP files: HELP.COM and 
HELP.HLP. The HELP.COM file is the command file that processes 
the text of the HELP.HLP file and displays it on the screen. The 
HELP.HLP file is a text file to which you can add customized informa- 
tion, but you cannot directly edit the HELP.HLP file. You must use the 
HELP.COM file to convert HELP.HLP to a file named HELP.DAT 
before you can edit or add your own text. 

This form of the HELP command has the following options: 

■ The EXTRACT option accesses the file HELP.HLP on the default 
drive and creates a file called HELP.DAT on the default drive. You 
can now invoke a word processing program to edit or add your own 
text to the HELP.DAT file. EXTRACT can be abbreviated to E. 

■ The CREATE option accesses your edited HELP.DAT file on the 
default drive and builds a revised HELP.HLP file on the default drive. 
CREATE can be abbreviated to C. 

You must add topics and subtopics to the HELP.DAT file in a specific 
format. A topic heading in the HELP.DAT file takes the form: 

///nTopicname<cr> 

The three backslashes are the topic delimiters and must begin in col- 
umn one. In the preceding format statement, n is a number in the range 
from 1 through 9 that signifies the level of the topic. A main topic 
always has a level number of 1. The first subtopic has a level number 
of 2. The next level of subtopic has a level number of 3, and so forth, 
up to a maximum of nine levels. Topicname is the name of your topic, 
and allows a maximum of twelve characters. The entire line is termi- 
nated with a carriage return. 

Use the following guidelines to edit and insert text into the HELP.DAT 
file. 

■ Topics should be placed in alphabetical order. 

■ Subtopics should be placed alphabetically within their respective 
supertopic. 

■ Levels must be indicated by a number 1-9. 



i DIC[TA[. HESEAkCrU'" 



The HELP Command CP/M 3 User's Guide 

Some examples of topic and subtopic lines in the HELP.HLP file follow 

///INEW UTIUTY<cr> 

///2C0MMANDS<cr> 

///3PARAMETERS<cr> 

///2EXAMPLES<cr> 

The Brst example illustrates the format of a main topic line. The second 
example shows how to number the first subtopic of that main topic. 
The third example shows how the next level subtopic under level 2 
should be numbered. The fourth example shows how to return to the 
lower level subtopic. Any topic name with a level number of 1 is a 
main topic. Any topic name with a level number of 2 is a subtopic 
within its main topic. 

When you are executing the HELP.COM file, you need only enter enough 
letters of the topic to unambiguously identify the topic name. When 
referencing a subtopic, you must type the topic name AND the sub- 
topic, otherwise the HELP program cannot determine which main topic 
you are referencing. You can also enter a topic and subtopic following 
the program's internal prompt, HELP>, as follows 

HELP>ED COMMANDS 

This form of HELP displays information about 
the editing program, ED. 



n 



n 



CP/M 3 User's Guide The HEXCOM Command 

The HEXCOM Command 



Syntax: HEXCOM filename 

Explanadon: The HEXCOM command is a transient utility that generates a com- 
mand file (filetypc COM) from a HEX input file. It names the output 
file with the same filename as the input file but with filetypc COM. 
HEXCOM always looks for a file with filetype HEX. 

Example: (^>HEXCOM B : PROGRAM 

In the preceding command, HEXCOM generates a command file 
PROGRAM.COM from the input hex file PROGRAM.HEX. 



S DIGITAL RESEARCH'" 



The INTTDIR Command CP/M 3 User's Guide — 

The INITDIR Command 

Syntax: INITDIR d: 

Explanarion: The INITDIR command can initialize a disk directory to allow date 
and lime stamping of files on thai disk or remove date and time stamps. 

You must use INITDIR to initialize the directory for any disk on which -~ 
you plan to record date and time stamps for your files. If the disk is 
blank, INITDIR initializes the directory to record date and time stamps. 
If files already exist on the disk, INITDIR checks the space available _ 
for date and time stamps in the directory. If there is not enough room 
for date and time stamps, INITDIR does not initialize the directory and 
returns an error message. 

After you initialize the directory for date and time stamps, you must 
use the SET command to specify time stamp options on the disk. 

Examples: (\> INITDIR Ct 

The system prompts to confirm: _ 

INITDIR WILL ACTiyflTE TlflE STAMPS FOR SPECIFIED DRIVE. 
Do you really want to re-format the directory: C (Y/N)? 

If the directory has previously been initialized for date and time stamps, 
INITDIR displays the message: 

Director/ already re-f o rtnat t ed 

Do you wish to recoyer date/time directory space 

(Y/N)? _ 

Enter Y to reinitialize the directory to eliminate date and lime stamps. 
If you enter N, date and time stamping remains active on your disk 
and INITDIR displays the following message: ~" 

Do you want the existing date/time stamps cleared (Y/N)? 

Enter Y to clear the existing stamps. Enter N to keep the existing date 
and time stamps. 

IS DIGITAL RESEARCH'- 



CP/M 3 User's Guide The LIB Command 

The LIB Command 



Syntax: LIB filespec{[I|M|P|D]} 

LIB filespec{[I|M|P]) - filespec{modifier} 

{,filespec{ modifier} ... } 

Explanation: A library file contains a collection of object modules. Use the LIB utility 
to create libraries, and to append, replace, select, or delete modules 
from an existing library. You can also use LIB to obtain information 
about the contents of library files. 

LIB creates and maintains library files that contain object modules in 
Microsoft® REL format. These modules are produced by Digital 
Research's relocatable macro-assembler program, RMAC, or any other 
language translator that produces modules in MicroSoft REL format. 

LINK-80'" links the object modules contained in a library to other 
object files. LlNK-80 automatically selects from the library only those 
modules needed by the program being linked, and then forms an exe- 
cutable file with a filetype of COM. 

The library file has the filetype REL or IRL depending on the option 
you choose. Modules in a REL library file must not contain backward 
references to modules that occur earlier in the library, because LINK- 
80 currently makes only one pass through a library. 



E DIGITAL RESEARCH" 



The LIB Command 



CP/M 3 User's Guide 



Table 5-8. LIB Options 



Option 



Meaning 



The INDEX option creates an indexed library file of 
type IRL. LINK-80 searches faster on indexed Hbrar- 
ies than on n on indexed iibraries. 

The MODULE option displays module names. 

The PUBLICS option displays module names and the 
public variables for the new library file. 

The DUMP option displays the contents of object 
modules in ASCII form. 



Use modifiers in the command line to instruct LIB to delete, replace, or 
select modules in a library file. Angle brackets enclose the modules to 
be deleted or replaced. Parentheses enclose the modules to be selected. 

Unless otherwise specified, LIB assumes a filetype of REL for all source 
filenames. When you follow a filename by a group of module names 
enclosed in parentheses, these modules are included in the new library 
file. If modules are not specified, LIB includes all modules from the 
source file in the new library file. 





Table 5-9. LIB Modifiers 


Modifier 


Meaning 


Delete 


<module=> 


Replace 


< module = filename. REL> 




If module name and filename are the same this 




shorthand can be used: 




<filename> 


Select 


(modFIRST-modLAST.modl ,mod2 modN) 



RESEARCH™ 



CP/M 3 User's Guide The LIB Command 



Examples: A>L7B TEST4CP3 

A>L/B TEST5LP1=FILE1 >F1LE2 

The first example displays alt modules and publics in TEST4.REL. The 
second example creates TEST5.REL from FlLEl.REL and FILE2.REL, 
and displays all modules and publics in TEST5.REL. 

A>LJfl TEST=TEST1 (MODI >tiODa) .TEST2 (CI -Ca ,CB) 

In the preceding example LIB creates a library file TEST.REL from 
modules in two source files. TESTl.REL contributes MODI and MOD4. 
Llfi extracts modules CI, C4, all the modules located between them, 
and module C6 from TEST2.REL. 

ft>LIS FILE2=FILE3<M0DA = > 

In this example, LIB creates FlLEl.REL from FILE3.REL, omitting 
MODA which is a module in FILE3.REL. 

f\>L IB FILEG=FILE5<MaDft=FILEB,REL> 
A>L75 FILE6=FILE5<THISNAME> 

In the first example, MODA is in the existing FILE5.REL. When LIB 
creates FILE6.REL from FILE5.REL, FILEB.REL replaces MODA. 

In the second example, module THISNAME is in FILES. REL, When 
LIB creates FILE6.REL from FILE5.REL the file THISNAME.REL 
replaces the similarly named module THISNAME. 

fl>L/fl FILEl [ I ]=B !FILE2< PLOTS , FIND , SEARCH-DISPLAY } 

In this example LIB creates FILEl.IRL on drive A from the selected 
modules PLOTS, FIND, and modules SEARCH through the module 
DISPLAY, in FILE2.REL on drive B. 



m DIGITAL RESEARCH'" 



The LINK Command 

The LINK Command 



CP/M 3 User's Guide 



Syntax: 



LINK d:{filespec,{[o]} - }filespec{[o]H,.- 



Explanation: The LINK command combines relocatable object modules such as those 
produced by RMAC and PL/I-SO'" into a .COM file ready for execu- 
tion. Relocatable files can contain external references and publics. Relocat- 
able files can reference modules in library files. LINK searches the library 
files and includes the referenced modules in the output file. The LINK 
command is the LiNK-80 utility and are synonymous in this discussion. 
See the Programmer's Utilities Guide for the CPIM Family of Operat- 
ing Systems for a complete description of LINK-80. 

You can use LINK option switches to control the execution parameters 
of LINK-80. LINK options follow the file specifications and are enclosed 
within square brackets. Multiple switches are separated by commas. 



Table 5-10. LINK Options 



Option 


Meaning 


A 


Additional memory; reduces buffer space and writes 
temporary data to disk. 


B 


BIOS link in banked CP/M 3 system. Aligns data 
segment on page boundary; puts length of code seg- 
ment in header; defaults to SPR filetype. 


Dhhhh 


Data origin; sets memory origin for common and 
data area. 


Gn 


Go; set start address to label n. 


Lhhhh 


Load; change default load address of module to hhhh. 
Default OlOOH. 


Mhhhh 


Memory size; define free memory requirements for 
MP/M~ modules. 


NL 


No listing of symbol table at console. 



K DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



The LINK Command 



Table 5-10. (continued) 



Option 


Meaning 


NR 


No symbol table file. 


OC 


Output COM command file. Default. 


OP 


Output PRL page relocatable file for execution under 
MP/M in relocatable segment. 


OR 


Output RSP Resident System Process file for execu- 
tion under MP/M. 


OS 


Output SPR System Page Relocatable file for execu- 
tion under MP/M. 


Phhhh 


Program origin; changes default program origin 
address to hhhh. Default is OlOOH. 


Q 


Lists symbols with leading question mark. 


s 


Search preceding file as a library. 


$Cd 


Destination of console messages, d, can be X for 
console, Y for printer, or Z for zero output. Default 
isX. 


$ld 


Source of intermediate files; d is disk drive A-P. 
Default is current drive. 


$Ld 


Source of library files; d is disk drive A-P. Default is 




current drive. 


$Od 


Destination of objea file; d can be Z, or disk drive 
A-P. Default is to same drive as first file in the LINK- 
80 command. 


$Sd 


Destination of symbol file; d can be Y, Z, or disk 
drive A-P. Default is to same drive as first file in 
LINK- 80 command. 



E DIGITAL RtSEAKCH'" 



The LINK Command CP/M 3 User's Guide 



Examples: (\>LINK blMYFILE[NRJ 

LINK-80 on drive A uses as input MYFiLE.REL on drive B and pro- 
duces the executable machine code file MYFILE.COM on drive B. The 
[NR] option specifies no symbol table file, 

fi>LINK ml ,m2pm3 

LINK-80 combines the separately compiled files ml, ml, and m3, resolves 
their external references, and produces the executable machine code 61c 
ml.COM. 



LINK-80 combines the separately compiled files ml, m2, and m3 and 
produces the executable machine code file m.COM. 

f\>LlNK MYFILEtFILESCsJ 

The [s] option tells LINK-80 to search FILE5 as a hbrary. LINK-80 
combines MYFILE.REL with the referenced subroutines contained in 
FILE5.REL on the default drive A and produces MYFILE.COM on 
drive A. 



RESEARCH- 



CP/M 3 User's Guide The MAC Command 

The MAC Command 

Syntax: MAC filename {Soptions} 

Explanation: MAC, the CP/M Macro Assembler, is a transient utility that reads 
assembly language statements from a disk file of filetype ASM. MAC 
assembles the statements and produces three output files with the input 
filename and output filetypes of HEX, PRN, and SYM. 

Filename. HEX contains Intel* hexadecimal format object code. You 
can debug the HEX file with a debugger, or use HEX COM to create a 
COM file and e 



Filename.PRN contains an annotated source listing that can be printed 
or examined at the console. The PRN file includes a 16-column wide 
listing at the left side of the page that shows the values of literals, 
machine code addresses, and generated machine code. An equal sign 
denotes literal addresses to eliminate confusion with machine code 
addresses. 

Filename. SYM contains a sorted list of symbols defined in the program. 

Before invoking MAC, you must prepare a source program file with 
the filetype ASM containing assembly language statements. 

You can direct the input and output of MAC using the options listed 
in the following table. Use a letter with the option to indicate the 
source and destination drives, console, printer, or zero output, Valid 
drive names are A through O. X directs output to the console. P directs 
output to the printer. Z specifies that output files will not be created. 



i DIGITAL RESEARCH- 



The MAC Command CP/M 3 User's Guide 

Table 5-11. Input/Output Options 



Option 



Meaning 



source drive for ASM file (A-O) 
dcstinarion drive for HEX file (A-O, Z) 



source drive for macro library LIB files called by the 
MACLIB statement. 



destination drive for PRN fUe (A-O, X, P, Z) 
destination drive for SYM file [A-O, X, P, Z) 



Table 5-12. Output File Modifiers 



Modifier 



Meaning 



+ L lists input lines read from macro library LIB files 

-L suppresses listing (default) 

+ M lists all macro lines as they are processed during 

assembly 
— M suppresses all macro lines as they are read during 

assembly 
*M lists only hex generated by macro expansions 

+Q lists all LOCAL symbols in the symbol list 

— Q suppresses all LOCAL symbols in the symbol list 

(default) 

-t-S appends symbol file to print file 

— S suppresses creation of symbol file 

-H produces a pass 1 listing for macro debugging in 

PRN file 
- 1 suppresses listing on pass 1 (default) 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide The MAC Command 



n 

Examples: A>«flC SAMPLE 



In the preceding example MAC is invoked from drive A and operates 
on the file SAMPLE.ASM also on drive A. 

fi>rtAC SAMPLE $PB AA HB SX 

In this example, an assembly option parameter list follows the MAC 
command and the source filename. The parameters direct the PRN file 
to drive B, obtain the ASM file from drive A, direa the HEX file to 
drive B, and send the SYM file to the console. You can use blanks 
between option parameters. 



a DIGITAL RESEARCH" - 



The PATCH Command CP/M 3 User's Guide 

The PATCH Command 

Syntax: PATCH filename {typ} {n} 

Explanation: The PATCH command displays or installs patch number n to the 
CP/M 3 system or CP/M 3 command files. 

Only CP/M 3 system files of filetype COM, PRL, or SPR can be patched 
with the PATCH command. If the ryp option is not specified, the PATCH 
utility looks for a file with a filetype of COM. 

The patch number n must be between 1 and 32 inclusive. 

Examples: A > Pfl TCH SHOU 2 

The preceding command patches the system SHOW.COM file with 
patch number 2. The system displays the following question: 

Do you u ant to indicate that Patch *2 
has been installed for SHOM . COM? V 

If the patch is successful, the system displays the message: 

Patch Installed 

If the patch is not successful, the system displays the following mes- 
sage: 

Patch not Installed 

One of the following error messages might be displayed: 

■ ERROR: Patch requires CP/M 3. 

■ ERROR: Invalid filetype typ. 

■ ERROR: Serial Number mismatch. 

■ ERROR: Invalid patch number n 



m DIGITAL RESEARCH™ 



— CP/M 3 User's Guide The PIP Command 

The PIP Command 

Syntax: PIP dest-fiIespec|d:{[Gn]} = src-fi!cspec{[o]H,...} | d: {[o]} 

Explanation: PIP is a transient utility that copies one or more files from one disk 
and/or user number to another. PIP can rename a file after copying it. 
PIP can combine two or more files into one file. PIP can also copy a 
character file from disk to the printer or other auxiliary logical output 
device. PIP can create a file on disk from input from the console or 
other logical input device. PIP can transfer data from a logical input 
device to a logical output device, thus the name Peripheral Interchange 
Program, 

PIP copies file attributes with the file. This includes Read-Write or 
Read-Only and SYS or DIR file attributes and the user-definable attri- 
butes Fl through F4. If a file is password-protected, you must enter the 
password in the command line following the filename and/or filetype to 
which it belongs. If the password fails, the file is skipped and the failure 
noted. 

When you specify a destination file with a password, PIP assigns that 
password to the destination file and automatically sets the password 
protection mode to READ. When you specify a destination file with no 
password, PIP does not assign a password to the destination file. When 
you specify only a destination drive, PIP assigns the same password and 
password proteaion mode to the destination file as specified in the 
source file. When you specify a destination file with a password, PiP 
automatically sets the password proteaion mode to READ. This means 
that you need a password to read the file, (See the SET command.) 

Single File Copy 

Syntax: PIP d:{[Gn]} = src-filespcc{[options]} 

PIP dcst-filespec{[Gn]} = d:{[options]} 
PIP dest-filespec{[Gn]y = src-filespec{[o]} 



4 DIGITAL RESEARCH'" 



The PIP Command CP/M 3 User's Guide 

Explanation: The first form shows the simplest way to copy a file. PIP looks for the 
file named by src-filespec on the default or optionally specified drive. 
PIP copies the file to the drive specified by d: and gives it the name 
specified by src-filespec. If you want, you can use the [Gn] option to 
place your destination file (dest-filespec) in the user number specified by 
n. The only option recognized for the destination file is [Gnj. Several 
options can be combined together for the source file specification (src- 
filespec}. See the Table 5-13, PIP options. 

The second form is a variation of the first. PIP looks for the file named 
by dest-filespec on the drive specified by d:, copies it to the default or 
optionally specified drive, and gives it the name specified by dest-filespec. 

The third form shows how to rename the file after you copy it. You 
can copy it to the same drive and user number, or to a different drive 
and/or user number. Rules for options are the same. PIP looks for the 
file specified by src-filespec, copies it to the location specified in dest- 
filespec, and gives it the name indicated by dest-filespec. 

Remember that PIP always goes to and gets from the current default 
user number unless you specify otherwise with the [Gn] option. 

Before you start PIP, be sure that you have enough free space in kilo- 
bytes on your destination disk to hold the entire file or files that you 
are copying. Even if you are replacing an old copy on the destination 
disk with a new copy, PIP still needs enough room for the new copy 
before it deletes the old copy. Use the DIR command to determine 
filesize and the SHOW command to determine disk space. If there is 
not enough space, you can delete the old copy first by using the ERASE 
command. 

Data is first copied to a temporary file to ensure that the endre data file 
can be construaed in the space available on the disk. PIP gives the 
temporary file the filename specified for the destination, with the file- 
type $J$. If the copy operation is successful, PIP changes the temporary 
filetype $$$ to the filetype specified in the destination. 

If the copy operation succeeds and a file with the same name as the 
destination file already exists, the old file with the same name is erased 
before renaming the temporary file. 



- HI DIGITAL RESEARCH- 



CP/M 3 User's Guide The PIP Command 

File anributes (DiR, SYS, RO, RW) are transferred with the files. 

If the existing destination file is set to Read-Only (RO), PIP asks you if 
you want to delete it. Answer Y or N. Use the [W] option to write over 
Read-Only files. 

You can include PiP options following each source name. There is one 
valid option ([Gn] — go to user number n) for the destination file speci- 
fication. Options are enclosed in square brackets. Several options can 
be included for the source files. They can be packed together or sepa- 
rated by spaces. Options can verify that a file was copied correctly, 
allow PIP to read a file with the system (SYS) attribute, cause PIP to 
write over Read-Only files, cause PIP to put a file into or copy it from 
a specified user number, transfer from lower- to upper-case, and much 
more. 

Examples: fi> PIP B:=A ioldfile.dat 

ftyPIPBsoldfile.dat = fl.- 

Both forms of this command cause PIP to read the file oldfile.dat from 
drive A and put an exact copy of it onto drive B. This is called the 
short form of PIP, because the source or destination names only a drive 
and does not include a filename. When using this form you cannot copy 
a file from one drive and user number to the same drive and user 
number. You must put the destination file on a different drive or in a 
different user number. (See the section on PIP Options, and the USER 
Command.) The second short form produces exactly the same result as 
the first one, PIP looks for the file oldfile.dat on drive A, the drive 
specified as the source. 

P>>PIPB:newfile.(iat=Pi:aidfile,dat 

This command copies the file oldfile.dat from drive A to drive B and 
renames it to newfile.dat. The file remains as oldfile.dat on drive A. 
This is the long form of the PIP command, because it names a file on 
both sides of the command hue. 



S DIGITAL REStARCH'" - 



The PIP Command CP/M 3 User's Guide 



fi,>PIP neufile.dat = aldfile.dat 

Using this long form of PIP, you can copy a file from one drive and 
user number (usually user because CP/M 3 automatically starts out 
in user — the default user number) to the same drive and user number. 
This gives you two copies of the same file on one drive and user num- 
ber, each with a different name. 

{\> PIP B: PROGRAM. BAK = Al PROGRAM . DATTGl J 

The preceding command copies the file PROGRAM.DAT from user 1 
on drive A to the current selected user number on drive B and renames 
the filetype on drive B to BAK. 

B>PJP Frairam2.dat = fli p ro3 rami . datCE V G3] 

In this command, PIP copies the file named programl.dat on drive A 
and echoes [E] the transfer to the console, verifies [V] that the two 
copies are exactly the same, and gets [G3] the file programl.dat from 
user 3 on drive A. Because there is no drive specified for the destina- 
tion, PIP automatically copies the file to the default user number and 
drive, in this case user and drive B. 



Multiple File Copy 

Syntax: PIP d:{[Gn]} ={d:}wildcard-fiIespec{[options]} 

Explanation: When you use a wildcard in the source specification, PIP copies match- 
ing files one-by-one to the destination drive, retaining the original name 
of each file. PIP displays the message COPYING followed by each 
filename as the copy operation proceeds. PIP issues an error message 
and aborts the copy operation if the destination drive and user number 
are the same as those specified in the source. 

Examples: f\>PIP B:=A!».COM 

This command causes PIP to copy all the files on drive A with the 
filetype COM to drive B. 



- II? DIGITAL RESEARCH™ 



CP/M 3 User's Guide The PIP Command 



This command causes PIP to copy all the files on drive A to drive B. 
You can use this command to make a back-up copy of your distribu- 
tion disk. Note, however, that this command does not copy the CP/M 3 
system from the system tracks. COPYSYS copies the system for you. 

fl>P7P B:=ft:PROG????.* 

The preceding command copies all files whose filenames begin with PROG 
from drive A to drive B. 

A>PIP B:CG13=A:*.Bft5 

This command causes PIP to copy all the files with a filetype of BAS on 
drive A in the default user number {user 0) to drive B in user number 1, 
Remember that the DIR, TYPE, ERASE, and other commands only access 
files in the same user number from which they were invoked. (See the 
USER Command.) 



n Combining Files 

Syntax: PIP dest-filespec{[Gn]} = src-filespec{[o]}, src-filcspeci[o]K,-} 

I I Eiqilanatioii: This form of the PIP command lets you specify two or more files in the 

source. PIP copies the files specified in the source from left to right and 

combines them into one file with the name indicated by the destination 

I I file specification. This procedure is called file concatenation. You can use 

' I the [On] option after the destination file to place it in the user number 

specified by n. You can specify one or more options for each source file. 

I Some of the options force PIP to copy files character- by- character. In 

these cases, PIP looks for a CTRL-Z character to determine where the 

nend of the file is. Alt of the PIP options force a charaaer transfer except 
the following: 

A, C, Gn, K, O, R, V, and W. 

I Copying data to or from logical devices also forces a character transfer. 



I m 



DTCITAL RESEARCH'" 



The PIP Command CP/M 3 User's Guide 



You can terminate PIP operations by typing CTRL-C. 

When concatenating files, PIP only searches the last record of a file for 
the CTRL-Z end-of-file character. However, if PIP is doing a character 
transfer, it stops when it encounters a CTRL-Z character. 

Use the [O] option if you are concatenating machine code files. The [O] 
option causes PIP to ignore embedded CTRL-Z (end-of-file) charaaers, 
which indicate the end-of-file character in text files, but might be valid 
data in object code files. 

Examples: fii>PIP NEUFILE=FILE1 iFILEZ ,F ILE3 

The three files named FlLEl, FILE2, and F1LE3 are joined from left to 
right and copied to NEWF1LE.$$$. NEWFILE.SSS is renamed to NEW- 
FILE upon successful completion of the copy operation. All source and 
destination files are on the disk in the default drive A. 

A>PIP BrX.BflS = y.BflS. B:Z.dAS 

The file Y.BAS on drive A is joined with Z.BAS from drive B and placed 
in the temporary file X.$$$ on drive B. The file X.$$$ is renamed to 
X.BAS on drive B when PIP runs to successful completion. 



Copy Files to and from Auxiliary Devices 

Syntax: PIPdest-filespec{[Gn]} - src-filespec {[o]} 

AUX: AUX:{[o]} 

CON: CON:{[o]} 

PRN: NUL: 

LST: EOF: 

Explanation: This form is a special case of the PIP command line that lets you copy 
a file from a disk to a device, from a device to a disk or from one device 
to another. The files must contain printable characters. Each peripheral 
device is assigned to a logical device that identifies a source device that 
can transmit data or a destination device that can receive data. (See the 
DEVICE command.) A colon follows each logical device name so it 
cannot be confused with a filename. Enter CTRL-C to abort a copy 
operation that uses a logical device in the source or destination. 

m DIGITAL RESEARCH'" 



CP/M 3 User's Guide The PIP Command 



The logical device names are listed as follows: 

■ CON: Console input or output device. When used as a source, usually 
the keyboard; when used as a destination, usually the screen. 

■ AUX: Auxiliary Input or Output Device. 

■ LST: The destination device assigned to the list output device, usually 
the printer. 

The following three device names have special meaning: 

■ NUL: A source device that produces 40 hexadecimal zeros. 

■ EOF: A source device that produces a single CTRL-Z, the CP/M 3 
end-of-file mark. 

■ PRN: The printer device with tab expansion to every eighth column, 
line numbers, and page ejects every sixtieth line. 

Examples: 5>PIP PRN: =CONi ,MYDflTft,DftT 

Characters are first read from the console input device, generally the 
keyboard, and sent direaly to your printer device. You type a CTRL-Z 
character to tell PIP that keyboard input is complete. At that time, PIP 
continues by reading character data from the file MYDATA.DAT on 
drive B, Because PRN: is the destination device, tabs are expanded, line 
numbers are added, and page ejects occur every sixty lines. 

Note that when the CON: device is the source you must enter both the 
carriage return (RETURN) and line-feed (LF) keys for a new line, 

{^>PIP B:FUNFILE.SUE = CON: 

Whatever you type at the console is written to the file FUNFILE.SUE on 
drive B, End the keyboard input by typing a CTRL-Z. 

fl>P/P LST:=CON: 

Whatever you type at the console keyboard is written to the list device, 
generally the printer. Terminate input with a CTRL-Z, 



El DIGITAL RESEARCH™ 



The PIP Command CP/M 3 User's Guide 



ft>PJP LST!=BiDR/iFT.TXT[TB3 



The file DRAFT.TXT on drive B is written to the printer device. Any tab 
charaaers are expanded to the nearest column that is a multiple of 8. 

fi>PJP PRN!=B: DRAFT. TXT 

The preceding command causes PIP to write the file DRAFT.TXT to the 
list device. It automatically expands the tabs, adds line numbers, and 
ejects pages after sixty lines. 



Multiple Command Mode 

Syntax: PIP 

Explanation: This form of the PIP command starts the PIP utility and lets you type 
multiple command lines while PIP remains in user memory. 

PIP writes an asterisk on your screen when ready to accept input com- 
mand lines. 

You can type any valid comnnand line described under previous PIP 
formats following the asterisk prompt. 

Terminate PIP by pressing only the RETURN key following the asterisk 
prompt. The empty command line tells PIP to discontinue operation and 
return to the CP/M 3 system prompt. 

Examples: A>PJP 

CP/M 3 PIP yERSIQN 3.0 
*NEUFILE=FILEi ,FIL£2 ,FILE3 

* APR0G.C0M=BPRDG,C0/1 

* A:=B!X.BfiS 
*B:=*.* 

* 'M 



This command loads the PIP program. The PIP command input prompt, 
*, tells you that PIP is ready to accept commands. The effects of this 
sequence of commands are the same as in the previous examples, where 

■ m DIGITAL RESEARCH'" 



„ CP/M 3 User's Guide The PIP Command 

I 
' 1 

the command line is included in the command tail. PIP is not loaded 
•* into memory for each command. To exit this PIP command mode, 

I I press RETURN or one of its equivalent control characters, CTRL-j or 

CTRL-M as shown. 

n 

' ' Using Options With PIP 

n Explanation: With options you can process your source file in special ways. You can 
expand tab characters, translate from upper- to lower-case, extract por- 
tions of your text, verify that the copy is correct, and much more. 

I j The PIP options are listed in Table 5-13 using n to represent a number 

and s to represent a sequence of characters terminated by a CTRL-Z. 

An option must immediately follow the file or device it affects. The option 

M must be enclosed in square brackets [ ]. For those options that require a 

1 I numeric value, no blanks can occur between the letter and the value. 

nYou can include the [Gn] option after a destination file specification. You 
can include a list of options after a source file or source device. An option 
list is a sequence of single letters and numeric values that are optionally 
^^ separated by blanks and enclosed in square brackets [ ]. 



1 DIGITAL RESEARCH™ 



The PIP Command 



CP/M 3 User's Guide 



Tabic 5-13. Pff Options 



Option 



Function 



Copy only the files that have been modified since the 
last copy. To back up only the files that have been 
modified since the last back-up, use PIP with the 
archive option, [A]. 

Prompt for confirmation before performing each copy 
operation. Use the [C] option when you want to copy 
only some files of a particular filetypc. 

Delete any characters past column n. This parameter 
follows a source file that contains lines too long to 
be handled by the destination device, for example, 
an 80-character printer or narrow console. The num- 
ber n should be the maximum column width of the 
destination device. 



Echo transfer at console, When this parameter fol- 
lows a source name, PIP displays the source data at 
the console as the copy is taking place. The source 
must contain character data. 

Filter form-feeds. When this parameter follows a 
source name, PIP removes all form-feeds embedded 
in the source data. To change form-feeds set for one 
page length in the source file to another page length 
in the destination file, use the F command to delete 
the old form-feeds and a P command to simultane- 
ously add new form-feeds to the destination file. 

Get source from or go to user number n. When this 
parameter follows a source name, PIP searches the 
directory of user number n for the source file. When 
it follows the destination name, PIP places the desti- 
nation file in the user number specified by n. The 
number must be in the range to 15. 



- IB DIGITAL RESEARCH'- 



CP/M 3 User's Guide 



The PIP Command 



Table 5-13. (continued) 



Option 



Hex data transfer, PIP checks all data for proper Intel 
hexadecimal file format. The console displays error 
messages when errors occur. 

Ignore :00 records in the transfer of Intel hexadeci- 
mal format file. The I option automatically sets the 
H option. 

Translate upper-case alphabetics in the source file to 
lower-case in the destination file. This parameter fol- 
lows the source device or filename. 

Add tine numbers to the destination file. When this 
parameter follows the source filename, PIP adds a 
line number to each line copied, starting with 1 and 
incrementing by one. A colon follows the line num- 
ber. If N2 is specified, PIP adds leading zeros to the 
line number and inserts a tab after the number. If the 
T parameter is also set, PIP expands the tab. 

Objea file transfer for machine code (noncharacter 
and therefore nonprintable) files, PIP ignores any 
CTRL-Z end-of-file during concatenation and trans- 
fer. Use this option if you are combining object code 
files. 

Set page length, n specifies the number of lines per 
page. When this parameter modifies a source file, PIP 
includes a page ejea at the beginning of the destina- 
tion file and at every n lines. If n = 1 or is not 
specified, PIP inserts page ejects every sixty lines. When 
you also specify the F option, PIP ignores form-feeds 
in the source data and inserts new form-feeds in the 
destination data at the page length specified by n. 



i DIGITAL RESEARCH" 



The PIP Command 



CP/M 3 User's Guide — 



Table 5-13. (continued) 



function 



Qs Quit copying from the source device after the string 

s. When used with the S parameter, this parameter 
can extract a portion of a source file. The string 
argument must be terminated by CTRL-Z. 

R Read system (SYS) files. Usually, PIP ignores files 

marked with the system attribute in the disk direc- 
tory. But when this parameter follows a source file- 
name, PIP copies system files, including their attri- 
butes, to the destination. 

Ss Start copying from the source device at the string s. 

The string argument must be terminated by CTRL- 
Z. When used with the Q parameter, this parameter 
can extract a portion of a source file. Both start and 
quit strings are included in the destination file. 

TiJ Expand tabs. When this parameter follows a source 

filename, PIP expands tab (CTRL-I) characters in the 
destination file. PIP replaces each CTRL-I with enough 
spaces to position the next character in a column 
divisible by n. 

U Translate lower-case alphabetic characters in the 

source file to upper-case in the destination file. This 
parameter follows the source device or filename. 

V Verify that data has been copied correctly. PIP com- 

pares the destination to the source data to ensure 
that the data has been written correctly. The desti- 
nation must be a disk file. 



- m DIGITAL RESEARCH- 



CP/M 3 User's Guide 



The PIP Command 



Table 5-13. (continued) 



Optio 



Function 



Write over files with RO (Read-Only) attribute. Usu- 
ally, if a PIP command tail includes an existing RO 
file as a destination, PIP sends a query to the console 
to make sure you want to write over the existing file. 
When this parameter follows a source name, PIP 
overwrites the RO file without a console exchange. 
If the command tail contains multiple source files, 
this parameter need follow only the last file in the 
list. 

Zero the parity bit. When this parameter follows a 
source name, PIP sets the parity bit of each data byte 
in the destination file to zero. The source must con- 
tain character data. 



Examples: f\>PIP NEUPROG,BAS=CODE .BfiSCLJ , DfiTfi.BflSCUJ 

This command constructs the file NEWPROG.BAS on drive A by join- 
ing the two files CODE.BAS and DATA.BAS from drive A. During the 
copy operation, CODE.BAS is translated to lower-case, while DATA.BAS 
is translated to upper-case. 

A> PIP CON:=UtDEFILE.BflSCDB0] 

This command writes the character file WIDEFILE.BAS from drive A 
to the console device, but deletes all characters following the 80th col- 
umn position. 

(\>PIP Bs-LETTER. TXTCEJ 

The file LETTER.TXT from drive A is copied to LETTER.TXT on 
drive B. The LETTER.TXT file is also written to the screen as the copy 

operation proceeds. 



I DIGITAL RESEARCH- 



The PIP Command CP/M 3 User's Guide 



{\>PIP LST:''6!L0NGPAGE.THTCFPG5J 

This command writes the file LONGPAGE.TXT from drive B to the 
printer device. As the file is written, form-feed characters are removed 
and reinserted at the beginning and every 65th line thereafter. 

B>PIP LST:=PROGRflM,BASi:NTBUJ 

This command writes the file PROGRAM. BAS from drive B to the 
printer device. The N parameter leils PIP to number each line. The T8 
parameter expands tabs to every eighth column. The U parameter 
translates lower-case letters to upper-case as the file is printed. 

fl>P/P PORTION. TXT=LETTER. TXTCSOear Sir-Z OSincerely'ZJ 

This command abstracts a portion of the LETTER.TXT file from drive 
A by searching for the character sequence "Dear Sir" before starting 
the copy operation, When found, the characters are copied to 
PORTION.TXT on drive A until the sequence "Sincerely" is found in 
the source file. 

B>PJP B!=ft!*.COMCVURJ 

This command copies all files with fileiype COM from drive A to drive 
B. The V parameter tells PIP to read the destination files to ensure that 
data was correctly transferred. The W parameter lets PIP overwrite any 
destination files that are marked as RO (Read-Only). The R parameter 
tells PIP to read files from drive A that are marked with the SYS (Sys- 
tem) attribute. 



- m DIGITAL RESEARCH'" 



^ CP/M 3 User's Guide The PUT Command 

<\ 

The PUT Command 

n 

' Syntax: PUT CONSOLE {OUTPUT TO} FILE filespec {[o]} 

PUT PRINTER {OUTPUT TO} FILE filespec {[o]} 
n PUT CONSOLE {OUTPUT TO} CONSOLE 

I I PUT PRINTER {OUTPUT TO} PRINTER 

n Explanation: The PUT command is a transient utility that lets you direct console 
output or printer output to a file. PUT allows you to direct the system 
to put console output or printer output to a file foe the next system 

n command or user program entered at the console. Or, PUT directs all 

subsequent console or printer output to a file when you include the 
SYSTEM option. 

n Console output is directed to a file until the program terminates. Then, 

console output reverts to the console. Printer output is directed to a file 
until the program terminates. Then printer output is directed back to 
n the printer. 

When you use the SYSTEM option, all subsequent console/printer out- 
put is directed to ^e specified file. This option terminates when you 
p] enter the PUT CONSOLE or PUT PRINTER command. 

The syntax for the option list is 

I j [{ECHO I NO ECHO} {FILTER | NO FILTER} | {SYSTEM}] 

^^ Table 5-14 defines the preceding option list. 



m DIGITAL RESEARCH'- - 



The PUT Command 



CP/M 3 User's Guide 



Table 5-14. PUT Options 



Option 



Meaning 



specifies that the output is echoed to the con- 
sole, ECHO is the default option when you direct 
console output to a file. 

specifies that the file output is not to be echoed 
to the console. 

specifies that filtering of control characters is 
allowed, which means that control characters 
are translated to printable characters. For 
example, an escape character is translated to "[. 

means that PUT does not translate control 
characters. This is the default option. 

specifies that system output and program out- 
put is written to the file specified by filespec. 
Output is written to the file until a subsequent 
PUT CONSOLE command redirects console 
output back to the console. 



Direct Console Output to a File 

Syntax: PUT CONSOLE {OUTPUT} TO FILE filespec {[o]} 

Explanation: The preceding form of the PUT command tells the system to direct 
subsequent console output to a file. 

Example: fi,> PUT CONSOLE OUTPUT TO FILE HOUT CECH02 

The preceding command directs console output to file XOUT with the 
output echoed to the console. 



!i DIGITAL RESEARCH" 



CP/M 3 User's Guide The PUT Command 

Put Printer Output to a File 

Synux: PUT PRINTER {OUTPUT TO} FILE filespec {[o]} 

Explanation: The preceding form of the PUT command direas printer output to a 
file. 

The options are the same as in the PUT CONSOLE command, except 
that option NO ECHO is the default for the PUT PRINTER command. 
Note thai if ECHO is specified, printer output is echoed to the printer. 

Examples: t\>PUT PRINTER OUTPUT TO FILE XOUT 
f>>MYPROG 

The preceding example directs the printer output of program MYPROG 
to file XOUT. The output is not echoed to the printer. 

ft>PU7 PRINTER OUTPUT TO FILE X0UT2 [ECHO , SYSTEM J 

The preceding command directs all printer output to file XOUT2 and 
to the printer, and the PUT is in effea until you enter a PUT PRINTER 
OUTPUT TO PRINTER command. 

The printer output can be directed to one or more files. The output to 
these files is terminated when you revert printer output to the printer 
using the following command: 

PUT PRINTER OUTPUT TO PRINTER 



Tenninate Console Output to a File 

Syntax: PUT CONSOLE {OUTPUT TO) CONSOLE 

Explanation: The preceding form of the PUT command directs console output to the 
console. 

Example: (^> PUT CONSOLE OUTPUT TO CONSOLE 

The preceding command directs console output to the console. 

E Dl<;iTAL RESEARCH"' 



The PUT Command CP/M 3 User's Guide 

Terminate Printer Output to a File 

Syntax: PUT PRINTER {OUTPUT TO} PRINTER 

Explanarion: The preceding form of the PUT command directs the printer output to 
the printer. 

Example: f\>PUT PRINTER OUTPUT TO PRINTER 

The preceding example directs printer output to the printer. 



- H DIGITAL RESEARCH- 



il 



CP/M 3 User's Guide The RENAME Command 

The RENAME Command 



Syntax: RENAME {new-filespec = old-filespec} 

Explanation: The RENAME command lets you change the name of a file that is 
cataloged in the directory of a disk. It also lets you change several 
filenames if you use wildcards in the filespecs. You can abbreviate 
RENAME to REN. 

The new-filespec must not be the name of any existing file on the disk. 
The old-filespec identifies an existing file or files on the disk. 

The RENAME command changes the file named by old-filespec to the 
name given as new-filespec. 

RENAME does not make a copy of the file. RENAME changes only 
the name of the file. 

If you omit the drive specifier, RENAME assumes the file to rename is 
on the default drive. You can include a drive specifier as a part of the 
newname. If both file specifications name a drive, it must be the same 

If the file given by oldname does not exist, RENAME displays the 
following message on the screen: 



If the file given by newname is already present in the directory, RENAME 
displays the following message on the screen: 

Not renamed: filenatneftxp file al ready exists* 
delete (Y/N)? 

If you want to delete the old file, type Y to delete. Otherwise, type N 
to keep the old file and not rename the new file. 



CrTAL RESEARCH"' 



The RENAME Command CP/M 3 User's Guide 

If you use wildcards in the filespecs, the wildcards in the new filespec 
must correspond exactly to the wildcards in the old filespec. For exam- 
ple, in the following two commands, the wildcard filespecs correspond 

exactly: 

ft>/?EW *.Tyi=*.TEX 
f\>REN ft*, T* = 5*. T* 

In the following example, the wildcards do not match and CP/M 3 
returns an error message. 

fl>/?EA/ ft*. TEX=A.T* 

Examples: fk>RENAME NEUASM . BftS=OLDFILE .BftS 

The file OLDFILE.BAS changes to NEWASM.BAS on drive A. 

(\> RENAME 

The system prompts for the filespecs: 

Enter New Name-.X.PRN 

Ente r Did Name: Y.PRN 

Y .PRN=X .PRN 

A> 

File Y.PRN is renamed X.PRN on drive A. 

a>REN ftiX.PAS = Y.PLI 

The file Y.PLI changes to X.PAS on drive A. 

fi>RENAME S* . TEX=A* , TEX 

The preceding command renames all the files matching the wildcard 
A* .TEX to files with filenames matching the wildcard S'.TEX, 
respectively. 



- ®l DIGITAL RESEARCH™ 



CP/M 3 User's Guide The RENAME Command 



(^>REN BsNBULIST=B!DLDLIST 

The tile OLDLIST changes to NEWLIST on drive B. Because the sec- 
ond drive specifier, B: is implied by the first, it is unnecessary in this 
example. The pieceding command line has the same effect as the 
following: 

f\>REN B!NEULIST = OLDLIST 



ft>REN NEULIST=B:OLDLIST 



i DIGITAL RESEARCH'" 



The RMAC Command 

The RMAC Command 



CP/M 3 User's Guide 



Syntax: 



RMAC filespec {$Rd | $Sd | $Pd} 



Explanation: RMAC is a relocatable macro assembler that 
ASM into REL files that can be linked to creat 



assembles files of type 
COM files. 



The RMAC command options specify the destination of the output 
files. The additional specifier d defines the destination drive of the 
output files. A-O specifies drives A through O. X means output to the 
console, P means output to the printer, and Z means zero output. Table 
5-15 lists the RMAC command options. 



Table 5-15. RMAC Command Options 



R drive for REL file 
S drive for SYM file 
P drive for PRN file 



(A-O, Z) 
{A-O, X, P, Z) 
(A-O, X, P, Z) 



In the MAC command, the assembly parameter of H controls the des- 
tination of the HEX file. In the RMAC command this parameter is 
replaced by R, which controls the destination of the REL file; however, 
you cannot direa the REL file to the console or printer, RX or RP, 
because the REL file is not an ASCII file. 

Examples: f\>RMflC TEST tPX SB RB 

In the preceding example RMAC assembles the file TEST. ASM from 
drive A, sends the listing file (TEST. PRN) to the console, puts the 
symbol file (TEST.SYM) on drive B and puts the relocatable object file 
(TEST.REL) on drive B. 



ra DIGITAL RESEARCH™ 



CP/M 3 User's Guide The SAVE Command 

The SAVE Command 



Syntax: SAVE 

Explanation: The SAVE command copies the contents of memory to a file. To use 
the SAVE utility, first issue the SAVE command, then run your pro- 
gram which reads a file into memory. When your program exits, it 
exits to the SAVE utility. The SAVE utility prompts you for the filespec 
to which the memory is to be copied, and the beginning and ending 
address of the memory to be saved. 



Example: (\>SftVE 



The preceding command activates the SAVE utility. Now enter the 
name of the program that loads a file into memory. 



Next, 

When the program exits, SAVE intercepts the return to the system and 
prompts you for the filespec and the bounds of memory to be saved. 

SAyE yer 3.0 

File (or RETURN to exit )?duMP2, com 

Delete duwpZ. com?>' 

From?JOO 

jo?aoo 

A> 

The contents of memory from lOOH, hexadecimal, to 400H is copied 
to file DUMP2.COM. 



B DIGITAL RESEARCH" 



The SET Command CP/M 3 User's Guide 

The SET Command 



Syntax: SET[options] 

SET d: [options] 
SET filespec [options] 

Explanation: The SET command initiates password protection and time stamping of 
files in the CP/M 3 system. It also sets file and drive attributes, such as 
the Read-Only, SYS, and user-definable attributes. It lets you label a 
disk and password protect the label. 

The SET command include options chat affect the disk directory, the 
drive, or a file or set of files. The discussion of the SET command 
explicitly states which of the three categories are affected. 

To enable time stamping of files, you must first run INITDIR to format 
the disk directory. 



Set File Attributes 

Syntax: SET filespec [attribute- options] 

Explanation: The preceding SET command sets the specified attributes of a file or a 
group of files. 

Table 5-16. SET File Attributes 



Option 


Meaning 


DIR 


Sets the file from the SYS directory to the 
(DIR) attribute. 


SYS 


Gives the file the System SYS attribute. 


RO 


Sets the file attribute to allow Read-Only 


R\e 


Sets the file attribute to allow Read-Write 

access. 



El DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



The SET Command 



Table S-16. (continued) 



Option 



Meaning 



ARCHIVE = OFF Sets the archive attribute to off. This means 

that the file has not been backed up {archived). 
PIP with the [A] option can copy files with 
the archive attribute set to OFF. PIP with this 
option requires an ambiguous filespec and 
copies only files that have been created or 
changed since the last time they were backed 
up with the PIP[A] option. PIP then sets the 
archive attribute to ON for each file success- 
fully copied. 

ARCHIVE = ON Sets the archive anribute to on. This means 

that the file has been backed up (archived). 
The archive attribute can be turned on 
explicitly by the SET command, or it can be 
turned on by PIP when copying a group of 
files with the PIP [A] option. The archive 
attribute is displayed by DIR. 

Fl = ON|OFF Turns on or off the user-definable file attri- 

bute Fl. 

F2 = ON|OFF Turns on or off the user-definable file attri- 

bute F2. 

F3 = 0N|0FF Turns on or off the user-definable file attri- 

bute F3. 

F4 = ON|OFF Turns on or off the user-definable file attri- 

bute F4. 



I I Example: P,>SETMYFILE,TEX[ROSYSJ 

c^ The preceding command sets MYFILE.TEX to Read-Only and System. 



i DIGITAL RESEARCH" 



The SET Command CP/M 3 User's Guide 

f\> SET MYFILE.TEX LRU DIP] 

The preceding command sets MYFILE.TEX to Read-Write with the 
Directory (DIR) attribute. 



Set Drive Attribute 

Syntax: SET {d:} [RO] 

SET {d:} [RW] 

Explanation: The preceding SET commands set the specified drive to Read-Only or 
Read-Write. 

If a drive is set to Read-Only, PIP cannot copy a file to it, ERASE 
cannot delete a file from it, RENAME cannot rename a file on it. You 
cannot perform any operation that requires writing to the disk. When 
the specified drive is set to Read- Write, you can read or write to the 
disk in that drive. If you enter a CTRL-C at the system prompt, all 
drives are reset to Read-Write. 

Example: A > S£ 7 S ; f ffO J 

The preceding command sets drive B to Read-Only. 

Assign a Label to the Disk 

Syntax: SET {d:}[NAME = labelname.typ] 

Explanation: The preceding SET command assigns a label (name) to the disk in the 
specified or default drive. 

CP/M 3 provides a facility for creating a directory label for each disk. 
The directory label can be assigned an eight-character name and a 
three- character type similar to a filename and filetype. Label names 
make it easier to catalog disks and keep track of different disk direc- 
tories. The default label name is LABEL. 



m DIGITAL RESEARCH^' 



CP/M 3 User's Guide The SET Command 

Example: (\>SETENftME=DI5Kt00] 

The preceding example labels the disk on the default drive DISKIOO. 



Assign Password to the Label 

Syntax: SET [PASSWORD - password] 

SET [PASSWORD -<cr> 

Explanatioa: The first form of the preceding SET command assigns a password to 
the disk label. The second form of the command removes password 
protection from the label. 

You can assign a password to the label. If the label has no password, 
any user who has access to the SET program can set other attributes to 
the disk which might make the disk inaccessible to you. However, if 
you assign a password to the label, then you must supply the password 
to set any of the functions controlled by the label. SET always prompts 
for the password if the label is password-protected. 

Examples: (^>SETCP(^SSU0RD = SECRET1 
ft>SET [PfiSSUORD = <cr> 

The first command assigns SECRET to the disk label. The second com- 
mand nullifies the existing password. 

Note: If you use password protection on your disk, be sure to record 
the password. If you forget the password, you lose access to your disk 
or files. 



Enable/Disable Password Protection for Files on a Disk 

Syntax: SET [PROTECT = ON] 

SET [PROTECT = OFF] 

Explanation: The first form of the SET command turns on password protection for 
all the files on the disk. The password protection must be turned on 
before you can assign passwords to individual files or commands. 



IE DIGITAL RESEARCH'" - 



The SET Command CP/M 3 User's Guide 



The second SET command disables password protecrion for the files on 
your disk. 

After a password is assigned to the label and the PROTECT option is 
turned on, you are ready to assign passwords to your files. 

You can always determine if a disk is password -protected by using the 
SHOW command to display the label. 



Assign Passwords to Files 

Syntax: SET filespec[PASSWORD = password] 

Explanation: The preceding SET command sets the password for filespec to the pass- 
word indicated in the command tail. Passwords can be up to eight 
characters long. Lower-case letters are translated to upper-case. 

You can use wildcards in the filespec. SET assigns the specified pass- 
word to the files that match the wildcard-filespec. 

Note: always record the passwords that you assign to your files. 
Without the password, you cannot access those files unless password 
protection is turned off for the whole disk. If you forget the password 
to the directory label, you cannot turn off the password protection for 

the disk. 

Example: fi>5ET MYFILE, TEXCPASSUaRD=MYFILJ 

MYHL is the password assigned to file MYF1LE.TEX. 

Set Password Protection Mode for Files with Passwords 

Syntax: SET filespec [PROTECT -READ] 

SET filespec [PROTECT = WRITE] 
SET filespec [PROTECT = DELETE] 
SET filespec [PROTECT = NONE] 



i DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



The SET Command 



Explanation: You can assign one of four modes of password protection to your file. 
The protection modes are READ, WRITE, DELETE, and NONE and 
are described in the following table. 



Table 5-17. Password Protection Modes 



The password is required for reading, copying, 
writing, deleting, or renaming the file. 

The password is required for writing, deleting, or 
renaming the file. You do not need a password to 
read the file. 

The password is only required for deleting or re- 
naming the file. You do not need a password to 
read or modify the file. 

No password exists for the file. If a password exists, 
this modifier can be used to delete die password. 



Assign a Default Password 

Syntax: SET [DEFAULT = password] 

Explanation: The preceding set command assigns a default password for the system 
to use during your computer session. The system uses the default pass- 
word to access password-protected files if you do not specify a pass- 
word, or if you enter an incorrea password. The system lets you access 
the file if the default password matches the password assigned to the 
file. 

Example: B>SET * , TEX [ PfiSSUORD = SECRET , PROTECT=URITE] 

The preceding command assigns the password SECRET to all the TEX 
files on drive B. Each TEX file is given a WRITE protect mode to 
prevent unauthorized editing. 



B DIGITAL RESEARCH'" 



The SET Command CP/M 3 User's Guide 



Example: f\>SET[DEFftULT=dd3 

The preceding command instructs the system to use dd as a password 
if you do not enter a password for a pass word- protected file. 



Set Time Stamp Options on Disk 

Synux: SET [CREATE -ON] 

SET [ACCESS = ON] 
SET [UPDATE -ON] 

Explanation: The preceding SET commands allow you to keep a record of the time 
and date of file creation and update, or of the last access and update of 

your files. 

[CREATE = ON] turns on CREATE time stamps on the disk in 

the default drive. To record the creation time 
of a file, the CREATE option must have been 
turned on before the file is created. 

[ACCESS = ON] turns on ACCESS time stamps on the disk in 

the default drive. ACCESS and CREATE 
options are mutually exclusive. This means that 
only one can be in effect at a time. If you turn 
on the ACCESS time stamp on a disk that has 
the CREATE time stamp, the CREATE time 
stamp is automatically turned off. 

[UPDATE^ ON] turns on UPDATE rime stamps on the disk in 

the default drive. UPDATE time stamps rec- 
ord the time the file was last modified. 

To enable time stamping, you must first run INITDIR to format the 
disk directory for time and date stamping. 

Although there are three kinds of date/time stamps, only two date/time 
stamps can be associated with a given file at one rime. You can choose 
to have either a CREATE date or an ACCESS date for files on a partic- 
ular disk. 



S DIGITAL RESEARCH™ 



CP/M 3 User's Guide The SET Command 

When you set both UPDATE and CREATE time stamps, notice that 
editing a file changes both the UPDATE and CREATE time stamps. 
This is because ED does not update the original file but creates a new 
version with the name of the original file. 

Example: fii>SET[fiCCESS = ONJ 

The DIR with [FULL] option displays the following date and time 
stamps: 

0>DIR CFUU] 



ONE ,TEX 9K 71 Di r BU None 08/03/Bl 10i56 

THREE .TEX 12K 95 Oir RU Hint 09/05/Bl ISldS 

ruO .TEX lOH 7G Die RU None 08/10/91 0S;t3 

The access time stamps displayed show the time the file was last dis- 
played or edited. Note that displaying a filename in a direaory listing 
does not constitute an access and is not recorded. 

A>S£T CCREATE'ON >UPDfiTE=0N3 

The following DIR output below shows how files with create and update 
time stamps are displayed. 

t>DIR [FULL] 



GENLED .OflT 109K B73 Oir RH Non* 08/05/81 MiOl 08/01/81 09 : 3G 
RECEIPT8.0flT 59K a75 Dir RU Nont 08/08/Bl 12:11 08/01/81 09;fl0 
INVOICES.OflT 7GK SOB Dir RU NonE 0B/08/B1 OBsflB 08/01/Bl 10:15 



n . 



DIGITAL RESEARCH'" 



The SET Command CP/M 3 User's Guide 

Additional SET Examples 

Examples: A>S£T * .COMZSYS ,R0 >PASS=123 ,PR0T=REfiD3 

The preceding setting gives the most protection for all the COM files on 
drive A. With the password protection mode set to READ, you cannot 
even read one of the COM files without entering the password 123, 
unless the default password has been set to 123. Even if the correct 
password is entered, you still cannot write to the file because the file is 
Read-Only. 

A>S£T" *,COM [RU ,PROTECT=NONE fDIR] 

The preceding command reverses the protection and access attributes of 
the COM files affected by the previous example. After executing the 
preceding command, there is no password protection, the files of type 
COM can be read from or written to, and are set to DIR files. 



- m DIGITAL RESEARCH'" 



n 



n 



CP/M 3 User's Guide The SETDEF Command 

The SETDEF Command 

Syntax: SETDEF {d:{,d:{,d:{,d:}}}} {TEMPORARY = d:] | [ORDER = (typ {,typ})]} 

SETDEF [DISPLAY | NO DISPLAY] 
SETDEF [PAGE | NO PAGE] 

Explanation: The SETDEF command lets you display or define the disk search order, 
the temporary drive, and the filetype search order. The SETDEF defini- 
tions affect only the loading of programs and/or execution of SUBMIT 
(SUB) files. The SETDEF command also lets you turn on/off the DISPLAY 
and PAGE modes for the system. When DISPLAY mode is on, the system 
displays the location and name of programs loaded or SUB files executed. 
When PAGE mode is on, CP/M 3 utilities stop after displaying one full 
screen of information. Press any key to continue the display. 

The system usually searches the specified drive or the default drive for 
files. The user can use the SETDEF command, to extend the search for 
program files and submit files, for execution purposes only. 

Note: A CP/M 3 program file has a filetype of COM. A file containing 
commands to be executed by SUBMIT has a filetype of SUB. 

Display the Program Loading Search Definitions 

Syntax: SETDEF 

r^ Explanation: The preceding form of the SETDEF command displays the disk search 
j I order, the temporary drive, and the filetype search order. 



ij Assign the Drive for Temporary Files 

Syntax: SETDEF [TEMPORARY = D:] 

Explanation: The preceding form of the SETDEF command defines the disk drive tc 
be used for temporary files. The default drive used for temporary files i; 
_ the system default drive. 



m DIGITAL RESEARCH'" - 



The SETDEF Command CP/M 3 User's Guide 



Example: fOSETDEF [TBMPORflRY=C: J 

The preceding command sets disk drive C as the drive to be used for 
temporary files. 



Define the Disk Drive Search Order 

Syntax: SETDEF { d: {,d: {,d: {,d:}J}} 

Explanation: The preceding form of the SETDEF command defines the disks to be 
searched by the system for programs and/or submit files to be executed. 
The CP/M 3 default is to search only the default drive. 

Note; ■ can be substituted for d: to indicate that the default drive is 
to be included in the drive search order. 

Example: ft> SETDEF Cst* 

The preceding example tells the system to search for a program on drive 
C, then, if not found, search for it on the default drive. 



Define the Filetype Search Order 

Syntax: SETDEF [ ORDER = (typ i,typ}) ] 

where typ = COM or SUB 

Explanation: The preceding form of the SETDEF command defines the filetype search 
order to be used by system for program loading. The filetype, indicated 
as typ in the syntax line, must be COM or SUB. The CP/M 3 default 
search is for COM files only. 

Example: {\>SETDEF [ORDER" ( SUB ,COM ) J 

The preceding command instructs the system to search for a SUB file to 
execute. If no SUB file is found, search for a COM file. 



- *» DIGITAL RESEARCH'- 



n 



CP/M 3 User's Guide The SETDEF Command 

Turn On/Off System Display Mode 

Syntax: SETDEF [DISPLAY | NO DISPLAY] 

Explanation: The preceding command turns the system display mode on or off. The 
default system display mode is off. When the display mode is on, 
CP/M 3 displays the following information about a program file before 
loading it for execution: drive, filename, tiletype (if any), and user number 
(if not the default user number). 

Example: f\>SETDEF CDISPLflYJ 

The preceding command turns on the system display mode. The system 
now displays the name and location of programs loaded or submit files 
executed. For example, if you enter the PIP command after turning on 
the system display mode, CP/M 3 displays the following: 

fi>PIP 

A:PIP COM 

CP/M 3 PIP iJERSIDN 3.0 



indicating that the file PIP.COM was loaded from drive A under the 
current user number. If the current user number is not 0, and if PIP.COM 
does not exist under the current user number, then the system displays 
the location of PIP.COM as follows: 

m^ypip 

A:PIP COM (User 0) 
CP/M 3 PIP yERSIDN 3.0 



indicating that PIP.COM was loaded from drive A under user number 
0. This mode is in effect until you enter 

SETDEF [NO DJSPLAYJ 

to turn off the system DISPLAY mode. 



? DIGITAL RESEARCH '~' 



n 

The SETDEF Command CP/M 3 User's Guide — 

Turn On/Off System Page Mode 

Syntax: SETDEF [ PAGE] NO PAGE ] 

Explanation: The preceding command turns on/off the system page mode. When the -^ 
PAGE mode is set to on, CP/M 3 utilities stop after displaying one full 
screen of information, called a console page. The utilities resume after 
you press any key. __ 

The default setting of the system page mode is ON. 

Example: A>SE7"D£F [NO PftCEJ — 

The preceding command turns off the system page mode. CP/M 3 utilities 

do not pause after displaying a full console page, but continue to scroll. _ 



- m DIGITAL RESEARCH'" 



n 



CP/M 3 User's Guide The SHOW Command 

The SHOW Command 



Syntax: SHOW {diHtSPACE |LABEL |USERS |DIR |DRIVE]} 

I I Explanation: The SHOW command displays the following disk drive information: 

■ access mode and amount of free disk space 
n ■ disk label 

i ■ current user number 

■ number of files for each user number on the disk 
•^ • number of free directory entries for the disk 

' ■ drive characteristics 

n Display Access Mode and Disk Space Available 

Syntax: SHOW {d:H[SPACE]} 

I 1 Explanation: The preceding form of the SHOW command displays the drive, the access 
mode for that drive, and the remaining space in kilobytes for the specified 

n drive. SHOW by itself displays the information for all logged-in drives 

in the system. 

Examples: A > SHOW 6; 

nB: RMi Space: 9 idQSK 

ft > SHOW 

A: RM> Space: <^K 

--J B: RI4 • Space : S >d8Sh 

The first example shows that drive B has Read- Write access and it has 
9,488K bytes of space left. The second example shows that drive A also 
n is Read-Write and has only 4K hytes left and drive B is Read-Write and 

' has 9,488K bytes left. 

I Display Disk Label 
_ Syntax: SHOW {d:}[LABEL] 

Explanation: Tlie preceding form of the SHOW command displays disk label information. 

I m DIGITAL RESEARCH'-' 



The SHOW Command CP/M 3 User's Guide 

Example: fl>SHOW B:[LA5ELJ 

The preceding command displays the following for drive B; 

Labil far drive B: 

Directarr Passwds Stanp Staxp Label Created Label Updsied 
Label Re'id Create Update 

TOflSDISK. on an on 07/Oa/Bl 10:30 07/OB/Bl 09:30 

The first column, directory label, displays the name assigned to that 
drive directory. The second column, Passwds Reqd, shows that pass- 
word protection has been turned on for that drive. 

As described in the SET command, each file can have up to two time 
stamps. The first of these time stamps can be either the creation date 
and time for the file or the date and time of the last access to the file. 
Access is defined as reading from or writing to the file. The third 
column of the SHOW [LABEL] output displays both the type of stamp 
and whether or not it is on. In the preceding example, creation time 
stamps are given to new files as shown by the stamp create column 
heading. 

The fourth column displays the status of the second time stamp field, 
the update time stamp. Update time stamps display the date and time 
of the last update to a file, that is, the last time someone wrote to the 
file. In the SHOW [LABEL] display, update time stamps are turned on. 

Besides showing the password protection and the active time stamps on 
a drive, SHOW [LABEL] also displays the date and lime that the label 
was created and last updated. 

Display User Number Information 

Syntax: SHOW {d:}[USERS] 

Explanation: The preceding command displays the current user number and all the 
users on the drive and the corresponding number of files assigned to 
them. 



- m DIGITAL RESEARCH™ 



-^ CP/M 3 User's Guide The SHOW Command 

I 

Example: A>SHOW CUSERSJ 
^ flcliyeUser: 1 

I I AciiuB Files: Z 3 a 

A: « of files: 95 HO 1 2B 
,_ A: Numberoffreedirecloryentries:350 



n Display Number of Free Directory Entries 

Syntax: SHOW {d:}[DlR] 



Explanation: The preceding command displays the number of free directory entries 
ch the specified drive. 



ij Exampli 

n 
n 
n 
n 
n 



le: t\>SHOU ClCDIR] 

Ci Number of free directory entries: 24 



The preceding command shows that there are only 24 free directory 
entries on drive C. 



as DIGITAL RESEARCH'" 



The SHOW Command 



CP/M 3 User's Guide 



Display Drive Characteristics 

Syntax: SHOW {d:}[DRIVE] 

Explanation: The preceding form of the SHOW command displays the. drive charac- 
teristics of the specified drive. 

Example: A>SHDW CDRIVEJ 

The following is an example of the system display for the preceding 
command: 

A: Drive Characteristics 

3,600: 128 Byte Record Capacity 
450; Kilobyte Drive Capacity 

96: 32 Byte Directory Entries 

96: Checked Direaory Entries 
128: Records / Directory Entry 

16: Records / Block 

48: Sectors / Track 
512: Bytes / Physical Record 



- m DIGITAL RESEARCH'- 



CP/M 3 User's Guide The SID Command 

The SID Command 



SynUx: SID {pgm-filespec} {,sym-filespec} 

Explanadon: The SID (Symbolic Instruction Debugger) allows you to monitor and 
test programs developed for the 8080 microprocessor. SID supports 
real-time bteakpoints, fully monitored execution, symbolic disassembly, 
assembly, and memory display and fill functions. Utility programs are 
supplied with CP/M 3 that can be dynamically loaded with SID to 
provide traceback and histogram facilities. 

SID commands display memory and CPU registers and direct the break- 
point operations during the debugging session. 

Without a file specification SID loads into memory without a test pro- 
gram. Use this form to examine memory or to write and test simple 
programs using the A command. You must not use the SID commands 
G, T, or U, described later, until you have first loaded a test program. 

A SID command line with a pgm-filespec loads both SID and the test 
program into memory. If the filetype is omitted from the filespec, COM 
is assumed. SID optionally loads in a symbol table file specified by sym- 
filespec. The sym-filespec needs no filetype because SID looks for a file 
with filetype SYM. Use the C, G, T, or U command to begin execution 
of the test program under supervision of SID. 

Use CTRL-S to halt the screen display. CTRL-Q restarts the display. 
Abort lengthy displays by typing any keyboard character. Use CTRL-C 
to exit from SID. 

SID can address absolute memory locations through symbolic expres- 
sions. A symbohc expression evaluates to either an address or a data 
item. 



I DIGITAL RESEARCH'" 



The SID Command CP/M 3 User's Guide 

A symbolic expression can be a name from a SYM file produced from 
your program by a CP/M Macro Assembler, When you precede the 
symbolic expression with a period, SID returns its address in hexadeci- 
mal. When you precede the symbolic expression with the at sign, @, 
SID returns the 16-bit value stored at that location and the next contig- 
uous location. When you precede the symbolic expression with an equal 
sign, SID returns the 8-bit value stored at that location. For two-byte 
expressions, this is the low byte because the 8080 microprocessor stores 
the low value of a two-byte word first. 

A symboLc expression can be a literal value in hex, decimal, or ASCII, 
as indicated in the following list: 

■ SID uses hteral hex values as given, but truncates any digits in 
excess of four on the left. The leftmost digit is the most significant 
digit. The rightmost digit is the least significant digit. 

■ To indicate decimal values precede them with a pound sign, #. 
Decimal values that evaluate to more than four hex digits are eval- 
uated as the modulo of hex value FFFF. For example, 
#65534 = FFFEH, while #65536 = 0001H. 

■ SID translates literal ASCII character strings between apostrophes 
to the hex value of the two rightmost ASCII characters. 

You can combine symbolic expressions with the symbolic operators, + 
or — , to produce another symbolic expression. Symbohc expressions 
combined in this way can be used to calculate the offset of an indirectly 
addressed data item, for example a subscripted variable. A special up- 
arrow operator, *, can reference the top-of-stack item. A string of n 
operators can reference the nth stack item without changing stack con- 
tent or the stack pointer. 

Table 5-18 lists the SID commands with their corresponding parame- 
ters and options. The actual command letter is printed in boldface. The 
parameters are in lower-case and follow the command letter. Optional 
items are in braces. Replace the arguments with the appropriate sym- 
bolic expressions as listed. Where two symbolic expressions are needed, 
SID can calculate the second one from the first using the symbolic 
operators described previously. 



- m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



The SID Command 







Name 


Syntax 1 


Meaning 


Assemble 


As 


Enter assembly language statements, s is the start 
address. 


Call 


Cs {b{,d» 


Call to memory location from SID. s is the called 
address, b is the value of the BC register pair, 
and d is the value of the DE register pair. 


Display 


D{W}{sH,f) 


Display memory in hex and ASCII. W specifies 
a 16-bit v^ord format, s is the start address, 
and £ is the finish address. 


Load 


Epgm-filespec 
{,sym-filespec} 


Load program and symbol table for execution. 


Load 


E* sym-filespec 


Load a symbol table file. 


Fill 


Fs.f.d 


Fill memory with constant value, s is the start 
address, f is the finish address, and d is an 8- 
bit data item. 


Go 


G{p){,ai,b}} 


Begin execution, p is a start address, a is a tem- 
porary breakpoint, and b is a second tempo- 
rary breakpoint. GO exits SID by performing a 
warm boot. 


Hex 


H 

Ha 
Ha,b 


Displays all symbols with addresses in hex. The 
first syntax displays hex, decimal, and ASCII 
values of a. The second syntax performs num- 
ber and character conversion, where a is a sym- 
bolic expression, and the third syntax com- 
putes hex sum and difference of a and b, where 
a and b are symbolic expressions. 


Input 


Icommand tail 


Input CCP command line. 


List 


L {s}{,f} 


List 8080 mnemonic instructions, s is the start 
address, and f is the finish address. 



I® DIG! lAL RESEARCH™ - 



The SID Command 



CP/M 3 User's Guide 







Tabic 5-18. (continued) 


Name 


Syntax 


Meaning 


Move 


Ms,h,d 


Move memory block, s is the start address, h is 
the high address of the block, and d is the des- 
tination start address. 


Pass 


P{p{,c}} 


Pass point set, reset, and display, p is a perma- 
nent bteakpoint address, and c is initial value 
of pass counter. 


Read 


Rfilespec{,d} 


Read code/symbols, d is an offset to each 
address. 


Set 


S{W}s 


Set memory values, s is an address where value 
is sent, W is a 16-bit word. 


Trace 


T{n{,c}} 


Trace program execution, n is the number of 
program steps, and c is the utility entry address. 


Trace 


T{W}{n{,c}} 


Trace without call. W instructs SID not to trace 
subroutines, n is the number of program steps, 
and c is the utility entry address. 


Untrace 


U{W}{n{,c}} 


Monitor execution without trace, n is the num- 
ber of program steps, c is the utility entry 
address, W instructs SID not to trace 
subroutines. 


Value 


V 


Display the value of the next available location 
in memory (NEXT), the next location after the 
largest file read in (MSZE), the current value of 
the program counter (PC), and the address of 
the end of available memory (END). 


Write 


Wfilespec{,s, 


} Write the contents of a contiguous block of 
memory to filespec, s is the start address, f is 
the finish address. 


Examine 


x{f}W 


Examine/alter CPU state, f Is flag bit C, E, 1, 
M, or Z; r is register A, B, D, H, P or S, 



-m DIGITAL RESEAR( 



CP/M 3 User's Guide The SID Command 



Examples: A>SJ'D 

In the preceding example CP/M 3 loads SID from drive A into memory. 
SID displays the # prompt when it is ready to accept commands. 

fi>S;SID SftMPLE.HEX 

In the preceding example, CP/M 3 loads SID and the program file 
SAMPLE.HEX into memory from drive B, SID displays: 

NEXT MSZE PC END 
nnnn mmmm pppp eeee 

In the preceding example, nnnn is a hexadecimal address of the next 
free location following the loaded program, and mmmm is the next 
location after the largest program. This is initially the same value as 
NEXT, pppp is the initial hexadecimal value of the the program coun- 
ter, eeee is the hexadecimal address of the logical end of the TPA. 

»DFE00+>tl2B+5 

In the preceding example the first pound sign, #, is the SID prompt. 
This SID command, D, displays the values stored in memory start- 
ing at address FE80 [FEOO + #128) and ending at address FE85 
(FE80 + 5). 



SID Utilities 



The SID utilities HIST.UTL and TRACE.UTL are special programs that 
operate with SID to provide additional debusing facilities. The mech- 
anisms for system initialization, data collection, and data display are 
described in the CP/M SID" Symbolic Instruction Debugger User's 
Guide. The following discussion illustrates how a utility is activated. 
You load the utility by naming it as a parameter when invoking SID: 

SID filename.UTL 

In the preceding example filename is the name of the utility. Following 
the initial sign-on, the utility can prompt you for additional debugging 
parameters. 



m DIGITAL RESEARCH'" 



The SID Command CP/M 3 User's Guide 

The HIST utility creates a histogram [bar graph) showing the relative 
frequency of execution of code within selected program segments of the 
test program. The HIST utiiity allows you to monitor those sections of 
code that execute most frequently. 

Upon siart-up HIST prompts 

TYPE HISTOGRAM BOUNDS 

Enter the bounds in the following format: 

aaaa,bbbb 

for a histogram between locations aaaa and bbbb inclusive. Collect 
data in U or T mode, then display results. 

The TRACE utility obtains a traceback of the instructions that led to a 
particular breakpoint address in a program under test. You can collect 
the addresses of up to 256 instructions between pass points in U or T 
modes. 



- m DIGITAL RESEARCH™ 



n 



CP/M 3 User's Guide The SUBMIT Command 

The SUBMIT Command 

Syntax: SUBMIT {filespec} {argument} ... {argument} 

Explanation: The SUBMIT command lets you execute a group or batch of com- 
mands from a SUB file, which is a file with filetype of SUB. 

Usually, you enter commands one line at a time. If you must enter the 
same sequence of commands several times, you might find it easier to 
batch the commands together using the SUBMIT command. To do this, 
create a file and enter your commands in this file. The file is identified 
by the filename, and must have a filetype of SUB. When you issue the 
SUBMIT command, SUBMIT reads the file named by the filespec and 
prepares it for interpretation by CP/M 3. When the preparation is com- 
plete, SUBMIT sends the file to CP/M 3 line-by-line, as if you were 
typing each command. 

The SUBMIT command executes the commands from a SUB file as if 

you are entering the commands from the keyboard. 

You create the SUB file with the ED utility. It can contain CP/M 3 
commands, nested SUBMIT commands, and input data for a CP/M 3 
command or a program. 

You can pass arguments to SUB files when you execute them. Each 
argument you enter is assigned to a parameter in the SUB file. The first 
argument replaces every occurrence of $1 in the file, the second argu- 
ment replaces parameter $2, etc., up to parameter $9. For example, if 
your file START.SUB contains the following commands: 

ERA Sl.BAK 

DIRSl 

PIPSl = A:$2.COM 

and you enter the following SUBMIT command: 

P,>SUBMIT START SAM TEX 



i DIGITAL RESEARCH- 



The SUBMIT Command CP/M 3 User's Guide 

the argument SAM is substituted for every $1 in the START.SUB file, 
and TEX for every occurrence of $2 in the START.SUB file. SUBMIT 
then creates a file with the parameter substitutions and executes this 
file. This file now contains the following commands: 

ERA SAM.BAK 

DIR SAM 

PIPSAM = A:TEX.COM 

If you enter fewer arguments in the SUBMIT command than parame- 
ters in the SUB file, the remaining parameters are not included in the 
commands. 

If you enter more arguments in the SUBMIT command than parameters 
in the SUB file, the remaining arguments are ignored. 

To include an actual dollar sign, S in your SUB file, type two dollar 
signs, $$. SUBMIT replaces them with a single dollar sign when it 
substitutes an argument for a parameter in the SUB file. For example, 
if file AA.SUB contains line: 

MAC SI S$$2 

and you enter the following SUBMIT command: 

f>i>SUBMIT Aft ZZ SZ 

then the translated file contains the following: 

MAC ZZ $SZ 



Program Input Lines in a SUB File 

A SUB file can contain program input lines. Any program input is 
preceded by a less than sign, <, as in the following example: 

PIP 

<B:=#.ASM 

<CDN!=DUMP.ASf1 



m DIGITAL RESEARCH™ 



CP/M 3 User's Guide The SUBMIT Command 

The three Hnes after PIP are input hnes to the PIP command. The third 
line consists only of the < sign, indicating a carriage return. The car- 
riage return causes PIP to return to the system to execute the final DIR 
command. 

If the program terminates before using all of the input, SUBMir ignores 
the excess input lines and displays the following warning message: 

Uarnind: Pro9raM input ignored 

If the program requires more input than is in the SUB file, it expects 
you to enter the remaining input from the keyboard. 

You can enter control characters in a SUB file by using the usual con- 
vention of preceding the control character by an up-arrow character, J, 
followed by the letter to be converted to a control character. To enter 
an actual \ character, use the combination ]]. This combination trans- 
lates to a single | in the same manner that $S translates to a single $. 



The SUB File 

n 



The SUB file can contain the following types of lines: 

■ Any vahd CP/M 3 command 

■ Any valid CP/M 3 command with SUBMIT parameters 

■ Any data input line 

■ Any program input line with parameters ($0 to $9} 

CP/M 3 command lines cannot exceed 128 characters. 



m DIGITAL RESEARCH™ 



The SUBMIT Command CP/M 3 User's Guide 



Example: The following lines illustrate the variety of lines that can be entered in 

a SUB file: 

DIR 

DIR *.BAK 

MAC tl t*$a 

PIP LST:=tl .PRN[T*2 t3 *5] 

DIR *.ASM 

PIP 

<B;=#.ASM 

<CaN!=DUMP.ASM 

< 

DIR B: 



Executing the SUBMIT Command 

Syntax: SUBMIT 

SUBMIT filespec 

SUBMIT filespec argument ... argument 

If you enter only SUBMIT, the system prompts for the rest of the 
command. You enter the filespec and arguments. 

Example: P^ySUBMIT 

The system displays the following prompt. Enter filespec and arguments 
here, such as: 

Enter File lo Submit! START 6 TEX 

Another example could be 

f^> SUBMIT SUB fi 



m DIGITAL RESEARCH- 



•1 CP/M 3 User's Guide The SUBMIT Command 

Still another example using parameters is 
i I f\>SUBNIT flA ZZ SZ 

n where AA is the SUB file AA.SUB, ZZ is the argument to replace any 

occurrences of Si in the AA.SUB file and SZ is the argument to replace 
all occurrences of $2 in the AA.SUB file. 



The PROFILE.SUB Start-up File 

Every time you turn on or reset your computer, CP/M 3 automatically 
looks for a special SUB file named PROFILE.SUB to execute. If it does 
not exist, then CP/M 3 resumes normal operation. If the PROFILE.SUB 
file exists, the system executes the commands in the file. This file is 
convenient to use if you regularly execute a set of commands before 
you do your regular session on the computer. For example, if you want 
to be sure that you always enter the current dale and time on your 
computer before you enter any other commands, you can create the 
PROFILE.SUB file, with ED, and enter the DATE command as follows: 

DATE SET 

Then, whenever you bring up the system, the system executes the DATE 
command and prompts you to enter the date and time. By using this 
facility, you can be sure to execute a regular sequence of commands 
before starting your usual session. 



MDIGITAL RESEARCH'" 



The TYPE Command CP/M 3 User's Guide — 

The TYPE Command 

Syntax: TYPE {filespec {[PAGE]|[NO PAGE]}} 

Explanation: The TYPE command displays the contents of an ASCII charaaer file 
on your screen. The PAGE option displays the console listing in paged 
mode, which means that the console listing stops automatically after 
listing n lines of text, where n is usually the system default of 24 lines "" 
per page. {See the DEVICE command to set n to a different value.) 
Press any charaaer to continue listing another n lines of text. Press 
CTRL-C to exit back to the system. PAGE is the default mode. _ 

The NO PAGE option displays the console listing continuously. 

If you do not enter a file specification in the TYPE command the system "" 
prompts for a filename with the message: 

Enle r f i 1 enawe s — 

Respond with the filespec of the file you want listed. 

Tab characters occurring in the file named by the file specification are 
expanded to every eighth column position of your screen. 

At any time during the display, you can interrupt the listing by pressing ~ 
CTRL-S. Press CTRL-Q to resume the listing. 

Press CTRL-C to exit back to the system. — 

Make sure the file specification identifies a file containing charaaer 
data. 

If the file named by the file specification is not present on the specified 
drive, TYPE displays the following message on your screen: 



- m DIGITAL RESEARCH " 



CP/M 3 User's Guide The TYPE Command 

To list the file at the printer and on the screen, type a CTRL-P before 
entering the TYPE command line. To stop echoing console output at 
the printer, type a second CTRL-P, The type command displays the 
contents of the file until the screen is filled. It then pauses until you 
press any key to continue the display. 

Examples: A > TYPE MY PROG , PL I 

This command displays the contents of the file MYPROG.PU on your 
screen, a page at a time. 

(\>TYPE BiTHISFILE CNO PAGE J 

This command continuously displays the contents of the file THISFILE 
from drive B on your screen. 



i DIGITAL RESEARCH"" 



The USER Command CP/M 3 User's Guide 

The USER Command 

Syntax: USER {number} 

Explanation: The USER command sets the current user number. When you start 
CP/M 3, is the current user number. You can use a USER command 
to change the current user number to another in the range 0-15. 

CP/M 3 identifies every file with a user number. In general, you can 
access only files identified with the current user number. However, if 
you mark a file in user with the SYS attribute, the file can be accessed 
from all other user numbers. 

Examples: fi,>USER 

The system command prompts for the user number, as follows: 

Enter U5er«:5 
5A> 

The current user number is now 5 on drive A. 

P,>USER 3 
3A> 

This command changes the current user number to 3. 



- m Dir.rTAL research^" 



CP/M 3 User's Guide The XREF Command 

The XREF Command 

Syntax: XREF {d:} filename i$P} 

Explanation: The XREF command provides a cross-reference summary of variable 
usage in a program. XREF requires the PRN and SYM files produced 
by MAC or RMAC for the program. 

The SYM and PRN files must have the same filename as the filename 
in the XREF command tail. XREF outputs a file of type XRF. 

Examples: fii>XREF b sMYPROG 

In this example, XREF is on drive A. XREF operates on the file 
MYPROG.SYM and MYPROG.PRN which are on drive B. XREF pro- 
duces the file MYPROG.XRF on drive B. 

(\> XREF b! MY PROG $P 

In the preceding example, the $P option directs output to the printer. 

End of Section 5 



1 DIGITAL RESEARCH™ 



] 

n 

1 
1 



Section 6 
ED, The CP/M 3 Context Editor 



6.1 Introduction to ED 

To do almost anything with a computer you need some way to enter data, a way 
to give the computer the information you want it to process. The programs most 
commonly used for this task are called editors. They transfer your keystrokes at the 
keyboard to a disk file. CP/M 3's editor is named ED. Using ED, you can easily 
create and alter CP/M 3 text files. 

The correct command formal for invoking the CP/M 3 editor is given in 
Section 6.2, "Starting ED." After starting ED, you issue commands that transfer text 
from a disk file to memory for editing. Section 6.3, "ED Operation," details this 
operation and describes the basic text transfer commands that allow you to easily 
enter and exit the editor. 

Section 6,4, "Basic Editing Commands," details the commands that edit a file. 
Section 6.5, "Combining ED Commands," describes how to combine the basic com- 
mands to edit more efficiently. Although you can edit any file with the basic ED 
commands, ED provides several more commands that perform more complicated 
editing functions, as described in Section 6.6, "Advanced ED Commands." 

During an editing session, ED can return two types of error messages. Section 6.7, 
"ED Error Messages," lists these messages and provides examples that indicate how 
to recover from common editing error conditions. 



6.2 Starting ED 

Syntax: 

ED input-filespec {d: [ output- files pec} 

To start ED, enter its name after the CP/M 3 prompt. The command ED must be 
followed by a file specification, one that contains no wildcard characters, such as: 

A>ED MYFJLE.TEX 

m DIGITAL REStARCH'- 



CP/M 3 User's Guide 



The file specification, MYFILE.TEX in the preceding example, specifies a file to be 
edited or created. The file specification can be preceded by a drive specification, but 
a drive specification is unnecessary if the file to be edited is on your default drive. 
Optionally, the file specification can be followed by a drive specification, as shown in 
the following example: 

fi>ED MYFILE. TEX Bi 

[n response to this command, ED opens the file to be edited, MYFILE.TEX, on 
drive A, but sends all the edited material to a file on drive B. 

Optionally, you can send the edited material to a file with a different filename, as 
in the following example: 

fi>ED MYFILE.TEX YOURFILE.TEX 

The file with the different filename cannot already exist or ED prints the following 
message and terminates. 

Output File Exislst Erase It 

The ED prompt, *, appears at the screen when ED is ready to accept a command, 
as follows 

Pi>ED MYFILE.TEX 



If no previous version of the file exists on the current disk, ED automatically 
new file and displays the following message; 



Note: before starting an editing session, use the SHOW command to check the 
amount of free space on your disk. Make sure that the unused portion of your disk 
is at least as large as the file you are editing, or larger if you plan to add characters 
to the file. When ED finds a disk or direaory full, ED has only limited recovery 
mechanisms. These are explained in Section 6.7, "ED Error Messages." 



- m DIGITAL re,sear{:h™ 



CP/M 3 User's Guide 



6.3 ED Operation 

With ED, you change portions of a file that pass through a memory buffer. When 
you start ED with one of the preceding commands, this memory buffet is empty. At 
your command, ED reads segments of the source file, for example MYFILE.TEX, 
into the memory buffer for you to edit. If the file is new, you must insett text into 
the file before you can edit. Duiing the edit, ED writes the edited text onto a tempo- 
rary work file, MYF1LE.$$$. 

When you end the edit, ED writes the memory buffer contents to the temporary 
file, followed by any remaining text in the source file. ED then changes the name of 
the source file from MYFILE.TEX to MYFILE.BAK, so you can reclaim this original 
material from the back-up file if necessary. ED then renames the temporary file, 
MYFILE.$$$, to MYFILE.TEX, the new edited file. The following figure illustrates 
the telationship between the source file, the temporary work file, and the new file. 

Note: when you invoke ED with two filespecs, an input file and an output file, ED 
does not rename the input file to type BAK; therefore, the input file can be Read- 
only or on a write-proteaed disk if the output file is written to another disk. 



m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 




Figure 6-1. Overall ED Operation 



In the preceding figure, the memory buffer is logically between the source file and 
the temporary work file. ED supports several commands that transfer lines of text 
between the source file, the memory buffer, and the temporary, and eventually final, 
file. The following table lists the three basic text transfer commands that allow yeu 
to easily enter rhe editor, write text to the temporary file, and exit the editor. 



1 



CP/M 3 User's Guide 6-3 ED Operation 

Table 6-1. Text Transfer Commands 



Append the next n unprocessed source lines from the source file 
to the end of the memory buffer. 

Write the first n lines of the memory buffer to the temporary 
file free space. 

End the edit. Copy all buffered text to the temporary file, and 
copy all unprocessed source lines to the temporary file. Rename 
flies. 



6.3.1 Appending Text into the Buffer 

When you start ED and the memory buffer is empty, you can use the A (append) 
command to add text to the memory buffer. 

Note: ED can number lines of text to help you keep track of data in the memory 
buffer. The colon that appears when you start ED indicates that tine numbering is 
turned on. Type -V after the ED prompt to turn the line number display off. Line 
numbers appear on the screen but never become a part of the output file. 

The V (Verify Line Numbers) Command 

The V command turns the line number display in front of each line of text on or 
off. The V command also displays the free bytes and total size of the memory buffer. 
The V command takes the following forms: 

V, -V, ov 



n M 



DIGITAL RESEARCH™ 



6.3 ED Operation CP/M 3 User's Guide 

Initially, the line number display is on. Use -V to turn it off. If the memory buffer 
is empty, or if the current line is at the end of the memory buffer, ED represents the 
line number as five blanks. The OV command prints the memory buffer statistics in 
the form: 

free/total 

where free is the number of free bytes in the memory buffer, and total is the size of 
the memory buffer. For example, if you have a total of 48,253 bytes in the memory 
buffer and 46,652 of them are free, the OV command displays this information as 
follows 

aSB5Z/-38253 

If the buffer is full, the first field, which indicates free space, is blank. 

The A (Append) Command 

The A command appends, copies, lines from an existing source file into the mem- 
ory buffer. The A command takes the following form; 

nA 

where n is the number of unprocessed source hues to append into the memory buffer. 
If a pound sign, #, is given in place of n, then the integer 65,535 is assumed. Because 
the memory buffer can contain most reasonably sized source files, it is often possible 
to issue the command #A at the beginning of the edit to read the entire source file 
into memory. 

When n is 0, ED appends the unprocessed source lines into the memory buffer 
until the buffer is approximately half full. If you do not specify n, ED appends one 
line from the source file into the memory buffer. 

6.3.2 ED Exit 

You can use the W (Write) command and the E (Exit) command to save your 
editing changes. The W command writes lines from the memory buffer to the new 
file without ending the ED session. An E command saves the contents of the buffer 
and any unprocessed material from the source file and exits ED. 



m DIGITAL RESEARCH" 



n 



CP/M 3 User's Guide 6-3 ED Operation 

The W (Write) Command 

The W command writes lines from the buffer to the new file. The W command 
takes the form: 

nW 

where n is the number of lines to be written from the beginning of the buffer to the 
end of the new file. If n is greater than 0, ED writes n lines from the beginning of 
the buffer to the end of the new file. If n is 0, ED writes lines until the buffer is half 
empty. The OW command is a convenient way of making room in the memory buffer 
for more lines from the source file. If the buffer is full, you can use the OW command 
to write half the contents of the memory buffer to the new file. You can use the #W 
command to write the entire contents of the buffer to the new file. Then you can use 
the OA command to read in more lines from the source file. 

Note: after a W command is executed, you must enter the H command to reedit 
the saved lines during the current editing session. 

The E (Exit) Command 

An E command performs a normal exit from ED. The E command takes the form: 



followed by a carriage return. 

When you enter an E command, ED first writes all data lines from the buffer and 
the original source file to the S$S file. If a BAK file exists, ED deletes it, then renames 
the original file with the BAK filetype. Finally, ED renames the $$$ file from file- 
name.SSS to the original filetype and returns control to the operating system. 

The operation of the E command makes it unwise to edit a back-up file. When you 
edit a BAK file and exit with an E command, ED erases your original file because it 
has a BAK filetype. To avoid this, always rename a back-up file to some other filetype 
before editing it with ED. 

Note: any command that terminates an ED session must be the only command on 
the Une. 



i DIC;iTAL RESEARCH'- - 



6.4 Basic Editing Commands CP/M 3 User's Guide 

6.4 Basic Editing Commands 

The text transfer commands discussed previously allow you to easily enter and exit 
the editor. This section discusses the basic commands that edit a file. 



ED treats a file as a long chain of characters grouped together in lines. ED displays 
and edits characters and lines in relation to an imaginary device called the character 
pointer (CP). During an edit session, you must mentally picture the CP's location in 
the memory buffer and issue commands to move the CP and edit the file. 

The following commands move the character pointer or display text in the vicinity 
of the CP. These ED commands consist of a numeric argument and a single com- 
mand letter and must be followed by a carriage return. The numeric argument, n, 
determines the number of times ED executes a command; however, there are four 
special cases to consider in regard to the numeric argument: 

■ If the numeric argument is omitted, ED assumes an argument of 1. 

■ Use a negative number if the command is to be executed backwards through 
the memory buffer. The B command is an exception. 

■ If you enter a pound sign, #, in place of a number, ED uses the value 65,535 
as the argument. A pound sign argument can be preceded by a minus sign to 
cause the command to execute backwards through the memory buffer, -#. 

■ ED accepts as a numeric argument only in certain commands. In some 
cases, causes the command to be executed approximately half the possible 
number of times, while in other cases it prevents the movement of the CP. 



ia DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



6.4 Basic Editing Commands 



The following table alphabetically summarizes the basic editing commands and 
n their valid arguments. 



Table 6-2. Basic Editing Commands 



Command 


Action 


B, -B 


Move CP to the beginning (B) or end (-B) of the memory 
buffer. 


nC, -nC 


Move CP n characters forward (nC) or backward (-nC) 
through the memory buffer. 


nD, -iiD 


Delete n characters before (-nD) or after {nD) the CP. 


I 


Enter insert mode. 


Istring CTRL-Z 


Insert a string of characters. 


nK, -nK 


Delete (kill) n lines before the CP [-nK} or after the CP 
(nK). 


nL, -nL 


Move the CP n lines forward (nL) or backward {-nL) 
through the memory buffer. 


iiT, -nT 


Type n lines before the CP (-nT) or after the CP (nT). 


n, -n 


Move the CP n lines before the CP (-n) or after the CP (n) 
and display the destination Une. 



The following sections discuss ED's basic editing commands in more detail. The 
examples in these sections illustrate how the commands affect the position of the 
character pointer in the memory buffer. Later examples in Section 6.5, "Combining 
ED Commands," illustrate how the commands appear at the screen. For these sec- 
tions, however, the symbol * in command examples represents the character pointer, 
which you must imagine in the memory buffer. 



a DIGITAL RESEARCH" 



6.4 Basic Editing Commands CP/M 3 User's Guide 

6.4,1 Moving the Character Pointer 

This section describes commands that move the character pointer in useful incre- 
ments but do not display the destination line. Although ED is used primarily to 
create and edit program source files, the following sections present a simple text as 
an example to make ED easier to learn and understand. 

The B (Beginning/Bottom) Command 

The B command moves the CP to the beginning or bottom of the memory buffer. 
The B command takes the following forms: 



-B moves the CP to the end or bottom of the memory buffer; B moves the CP to the 
beginning of the buffer. 

The C (Charaaer) Command 

The C command moves the CP forward or backward the specified number of 
characters. The C command takes the following forms: 

nC, -nC 

when n is the number of characters the CP is to be moved. A positive number moves 
the CP towards the end of the line and the bottom of the buffer. A negative number 
moves the CP towards the beginning of the line and the top of the buffer. You can 
enter an n large enough to move the CP to a different hne. However, each line is 
separated from the next by two invisible characters: a carriage return and a line-feed, 
represented by <cr><lf>. You must compensate for their presence. For example, if 
the CP is pointing to the beginning of the line, the command 30C moves the CP to 
the next line: 

Emily Dickinson said,<cr><lf> 

"1 fin'd ecstasy in living ■ — <cr><!f> 



- m DIGITAL RESEARCH™ 



I 



CP/M 3 User's Guide 6.4 Basic Editing Commands 

The L (Line) Command 

The L command moves the CP the specified number of lines. After an L command, 
the CP always points to the beginning of a line. The L command takes the following 
forms: 

nL, -nL 

where n is the number of lines the CP is to be moved. A positive number moves the 
CP towards the end of the buffer. A negative number moves the CP back toward the 
beginning of the buffer. The command 2L moves the CP two lines forward through 
the memory buffer and positions the character pointer at the beginning of the line. 

"I find ecstasy in living ^<crXlf> 
the mere sense of living<cr><lf!> 
'is joy enough, "<cr><lf> 

The command -L moves the CP to the beginning of the previous line, even if the 
CP originally points to a character in the middle of the line. Use the special character 
to move the CP to the beginning of the current line. 

The n (Number) Command 

The n command moves the CP and displays the destination line. The n command 
takes the following forms: 



where n is the number of lines the CP is to be moved. In response to this command, 
ED moves the CP forward or backward the number of lines specified, then prints 
only the destination line. For example, the command -2 moves the CP back two 



Emily Dickinson said,<crXlf> 
*"I find ecstasy in living — <cr><lf> 
the mere sense of Iiving<cr><lf!> 
is joy enough." <cr><lf> 



n 



6.4 Basic Editing Commands CP/M 3 User's Guide 

A further abbreviation of this command is to enter no number at all. In response 
to a carriage return without a preceding command, ED assumes a n command of 1 
and moves the CP down to the next line and prints it, as follows 

Emily Dickinson said,<cr><lf> 
"I find ecstasy in living — <cr><lf> 
"the mere sense of living<cr><lf > 

Also, a minus sign, — , without a number moves the CP back one line. 

6.4.2 Displaying Memory Buffer Contents 

ED does not display the contents of the memory buffer until you specify which 
pan of the text you want to see. The T command displays text without moving the 



The T (Type) Command 

The T command types a specified number of lines from the CP at the screen. The ~ 
T command takes the forms 

nT, -nT „ 

where n specifies the number of lines to be displayed. If a negative number is entered, 
ED displays n lines before the CP. A positive number displays n lines after the CP. if 
no number is specified, ED types from the character pointer to the end of the line. "" 
The CP remains in its original position no matter how many lines are typed. For 
example, if the character pointer is at the beginning of the memory buffer, and you 
instruct ED to type four lines [4T), four lines are displayed at the screen, but the CP — 
stays at the beginning of line 1. 

"Emily Dickinson said,<cr><lf> 

"I find ecstasy in living ^<cr><lf> i 

the mere sense of living<cr><lf> 
is joy enough." <cr><tf> 

If the CP is between two characters in the middle of the line, a T command with 
no number specified types only the characters between the CP and the end of the 
line, but the character pointer stays in the same position, as shown in the following _ 

memory buffer example: 

"I find eo'stasy in liuinS - 

m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 6.4 Basic Editing Commands 

Whenever ED is displaying text with the T command, you can enter a CTRL-S to 
stop the display, then press any key when you are ready to continue scrolling. Enter 
a CTRL-C to abort long type-outs. 

6.4.3 Deleting Characters 

The D (Delete) Command 

The D command deletes a specified number of characters and takes the forms: 

nD, -nD 

where n is the number of characters to be deleted. If no number is specified, ED 
deletes the character to the right of the CP. A positive number deletes multiple 
charaaers to the right of the CP, towards the bonom of the file. A negative number 
deletes characters to the left of the CP, towards the top of the file. If the character 
pointer is positioned in the memory buffer as follows 

Emily Dickinson said,<cr><lf> 
"I find ecstasy in living — <cr><lf> 
the mere sense of living<cr><lf> 
is joy "enough. "<cr><lf> 

the command 6D deletes the six characters after the CP, and the resulting memory 
buffer looks like this: 

Emily Dickinson said,<cr><lf> 
"I find ecstasy in living — <cr><If> 
the mere sense of iiving<cr><lf> 
is joy "."<cr><lf> 

You can also use a D command to delete the <cr><lf> between two lines to join 
them together. Remember thai the <cr> and <lf> arc two characters. 



'I . 



DIGITAL RESEARCH™ 



6.4 Basic Editing Commands CP/M 3 User's Guide 

The K (Kill) Command 

The K command kills or deletes whole lines from the memory buffer and takes the 
forms; 



where n is the number of lines to be deleted. A positive number kills lines after the 
CP. A negative number kills lines before the CP. When no number is specified, ED 
kills the current line. If the character pointer is at the beginning of the second line, 

Emily Dickinson said,<cr><lf> 
■"i find ecstasy in living ■ — <cr><lf> 
the mere sense of Iiving<cr><lf> 
is joy enough. "<cr><lf> 

then the command -K deletes the previous line and the memory buffer changes: 

""I find ecstasy in living ^<cr><lf!> 
the mere sense of living<cr><lf> 
is joy enough." <crXlf> 

If the CP is in the middle of a line, a K command kills only the characters from 
the CP to the end of the line and concatenates the characters before the CP with the 
next line. A -K command deletes all the characters between the beginning of the 
previous line and the CP. A OK command deletes the characters on the line up to the 
CP. 

You can use the special # character to delete all the text from the CP to the 
beginning or end of the buffer. Be careful when using #K because you cannot reclaim 
lines after they are removed from the memory buffer. 

6.4.4 Inserting Characters into the Memory Buffer 

The 1 (Insert) Command 

To insert characters into the memory buffer from the screen, use the I command. 



- m DIGITAL RESEARCH™ 



I-, CP/M 3 User's Guide 



If you enter the command in upper-case, ED automatically 
upper-case. The I command takes the forms: 



6.4 Basic Editing Commands 

the string to 



Istring"Z 

When you type the first command, ED enters insert mode, in this mode, all key- 
strokes are added direaly to the memory buffer. ED enters charaaers in lines and 
does not start a new line until you press the enter key. 

A > EO B: QUO TE , TEX 

NEU FILE 
*i 
Emily Dickinson said* 
"I find ecstasy in living - 
the ms re sense of Hi/ ins 
is Joy enough • " 



Note: to exit from insert mode, you must press CTRL-2 or ESC. When the ED 
prompt, *, appears on the screen, ED is not in insert mode. 

In command mode, you can use CP/M 3 command line-editing control characters. 
In insert mode, you can use the control characters listed in Table 6-3. 



Table 6-3. CP/M 3 Line-editing Controls 



Result 



CTRL-H Delete the last character typed on the current line. 

CTRL-U Delete the entire line currently being typed. 

CTRL-X Delete the entire line currently being typed. Same as CTRL-U. 

Backspace Remove the last character. 



iC;iTAL RESEARCH™ 



6.4 Basic Edmng Commands CP/M 3 User's Guide 

When entering a combination of numbers and letters, you might find it inconve- 
nient to press a caps-lock key if your terminal translates the upper-case of numbers 
to special characters. ED provides two ways to translate your alphabetic input to 
upper-case without affecting numbers. The first is to enter the insert command letter 
in upper-case: 1. All alphabetics entered during the course of the capitalized com- 
mand, either in insert mode or as a string, are translated to upper-case. If you enter 
the insert command letter in lower-case, all alphabetics are inserted as typed. The 
second method is to enter a U command before inserting text. Upper-case translation 
remains in effect until you enter a -U command. 

The Istring'Z (Insert String) Command 

The second form of the 1 command does not enter insert mode. It inserts the 
character siring into the memory buffer and returns immediately to the ED prompt. 
You can use CP/M 3's line-editing control characters to edit the command string. 

To insert a string, first use one of the commands that position the CP. You must 
move the CP to the place where you want to insert a string. For example, if you 
want to insert a string at the beginning of the first line, use a B command to move 
the CP to the beginning of the buffer. With the CP positioned correctly, enter an 
insert string, as follows 

iln lB70t '2 

This inserts the phrase "In 1870," at the beginning of the first line, and returns 
immediately to the ED prompt. In the memory buffer, the CP appears after the 
inserted string, as follows 

In 1870," Emily Dickinson said,<cr><lf> 

6.4.5 Replacing Characters 

Th e S (Substitute) Command 

The S command searches the memory buffer for the specified string, but when it 
finds it, automatically substitutes a new string for the search string. Whenever you 
enter a command in upper-case, ED automatically converts the string to upper-case. 
The S command lakes the form: 

oSsearch string'Znew string 



CP/M 3 User's Guide 6.4 Bask Editing Commands 

where n is the number of substitutions to make. If no number is specified, ED 
searches for the next occurrence of the search string in the memory buffer. For 
example, the command 

sEmily DicKinsor'ZThe poet 

searches for the first occurrence of "Emily Dickinson" and substitutes "The poet." In 
the memory buffer, the CP appears after the substituted phrase, as follows 

The poet" said,<cr><lf> 

If upper-case translation is enabled by a capital S command letter, ED looks for a 
capitalized search string and inserts a capitalized insert string. Note that if you com- 
bine this command with other commands, you must terminate the new string with a 
CTRL-Z. 



6.5 Combining ED Commands 

It saves keystrokes and editing time to combine the editing and display commands. 
You can type any number of ED commands on the same line. ED executes the 
command string only after you press the carriage return key. Use CP/M 3's line- 
editing controls to manipulate ED command strings. 

When you combine several commands on a line, ED executes them in the same 
order they are entered, from left to right on the command line. There are four 
restrictions to combining ED commands: 

■ The combined-command line must not exceed CP/M 3's 128 character 
maximum. 

■ If the combined-command line contains a character string, the line must not 
exceed 100 charaaers. 

■ Commands to terminate an editing session must not appear in a combined- 
command line. 

■ Commands, such as the I, J, R, S, and X commands, that require character 
strings or filespecs must be either the last command on a line or must be 
terminated with a CTRL-Z or ESC character, even if no character string or 
files pec is given. 



i DIGITAL RESEARCH™ 



6.5 Combining ED Commands CP/M 3 User's Guide — 

While the examples in the previous section show the memory buffer and the posi- 
tion of the character pointer, the examples in this section show how the screen looks "" 
during an editing session. Remember that the character pointer is imaginary, but you 
must picture its location because ED's commands display and edit text in relation to 
the character pointer. -^ 

6.5.1 Moving the Character Pointer 

To move the CP to the end of a line without calculating the number of characters, — 
combine an L command with a C command, L-2C. This command string accounts 
(or the <cr><lf> sequence at the end of the line. 

Change the C command in this command string to move the CP more characters 
to the left. You can use this command string if you must make a change at the end 
of the line and you do not want to calculate the number of characters before the 
change, as in the following example: ~ 

ii *T 

1: Emily DicKinson saidi _ 

1 : *L-?CT 



6.5.2 Displaying Text 

A T command types from the CP to the end of the line. To see the entire line, you 
can combine an L command and a T command. Type Olt lo move the CP from the 
middle to the beginning of the line and then display the entire line. In the following 
example, the CP is in the middle of the line. OL moves the CP to the beginning of 
the line, T types from the CP to the end of the line, allowing you to see the entire 
line. 



of liuins 
*OLT 
the mere sense of 1 i 



The command OTT displays the entire line without moving the CP. 



m DIGITAL RESEARCH" 



CP/M 3 User's Guide 6.S Combining ED Commands 

To verify that an ED command moves the CP correctly, combine the command 
with the T command to display the line. The following example combines a C 
command and a T command. 

2: *BCT 
ecstasy in liuins - 



Ehtily Dickinson 
"I find ecstasy 
the mere sense o 
is Joy enough." 



6.5.3 Editing 

To edit text and verify corrections quickly, combine the edit commands with other 
ED commands that move the CP and display text. Command strings like the one 
that follows move the CP, delete specified characters, and verify changes quickly. 

*15C5D0LT 
Emily Dickinson I 



Combine the edit command K with other ED commands to delete entire lines and 
verify the corrertion quickly, as follows 

1: *ZL2KBvT 

1: Ehtilv Dickinson saidt 

2: "I find ecstasy in liuin3 - 

1: * 

The abbreviated form of the I (insert) command makes simple textual changes. To 
make and verify these changes, combine the 1 command string with the C command 
and the OLT command string as follows. Remember that the insert string must be 
terminated by a CTRL-Z. 

1: *2QCi to a friend'ZOLT 

1: Emily Dickinson said to a friendi 



^DIGITAL RESEARCH " 



6.6 Advanced ED Commands CP/M 3 User's Guide 

6.6 Advanced ED Commands 

The basic editing commands discussed previously allow you to use ED for all your 
editing. The following ED commands, however, enhance ED's usefulness. 

6.6.1 Moving the CP and Displaying Text 

The P (Page) Command 

Although you can display any amount of text at the screen with a T command, it 
is sometimes more convenient to page through the buffer, viewing whole screens of 
data and moving the CP to the top of each new screen at the same time. To do this, 
use ED's P command. The P command takes the following forms: 



where n is the number of pages to be displayed. If you do not specify n, ED types 
the 23 lines following the CP and then moves the CP forward 23 lines. This leaves 
the CP pointing to the first charaaer on the screen. 

To display the current page without moving the CP, enter OP, The special character 
prevents the movement of the CP. If you specify a negative number for n, P pages 
backwards towards the top of the file. 

The n: (Line Number) Command 

When line numbers are being displayed, ED accepts a line number as a command 
to specify a destination for the CP. The line number command takes the following 
form: 



where n is the number of the destination line. This command places the CP at the 
beginning of the specified line. For example, the command 4; moves the CP to the 
beginning of the fourth line. 

Remember that ED dynamically renumbers text lines in the buffer each time a line 
is added or deleted. Therefore, the number of the destination line you have in mind 
can change during editing. 



a DIGITAL RESEARCH™ 



-^ CP/M 3 User's Guide 6.6 Advanced ED Commands 

1 

The :n [Through Line Number) Command 

n 

[ . The inverse of the line number command specifies that a command should be 

executed through a certain line number. You can use this command with only three 
ED commands: the K (kill) command, the L (line) command, and the T (type) com- 

I I mand. The :n command takes the following form: 

:ncomrnand 

I I where n is the Hoe number through which the command is to be executed. The :n 
part of the command does not move the CP, but the command that follows it might. 

-1 
j You can combine n: with :n to specify a range of lines through which a command 

should be executed. For example, the command 2::4T types the second, third, and 

fourth lines: 



d Bcstasf in liyin3 
re sense at liuinS 
e n u a h t " 



6.6.2 Finding and Replacing Character Strings 

ED supports a find command, F, that searches through the memory buffer and 
places the CP after the word or phrase you want. The N command allows ED to 
search through the entire source file instead of just the buffer. The J command 
searches for and then juxtaposes character strings. 

The F (Find) Command 

The F command performs the simplest find function; it takes the form: 

nFstring 

where n is the occurrence of the string to be found. Any number you enter must be 
positive because ED can only search from the CP to the bottom of the buffer. If you 
enter no number, ED finds the next occurrence of the string in the file. In the follow- 
ing example, the second occurrence of the word living is found. 

1: *2flivinS 



m DIGITAL RESEARCH'" - 



6.6 Advanced ED CommaDds CP/M 3 User's Guide 

The character pointer moves to the beginning of the third line where the second 
occurrence of the word "Hving" is located. To display the line, combine the find 
command with a type command. Note that if you follow an F command with another 
ED command on the same line, you must terminate the string with a CTRL-Z, as 
follows 

1 : *2fliuins-Z01t 

3: * the mere sense of 1 iuinS 

it makes a difference whether you enter the F command in upper- or lower-case. If 

you enter F, ED internally translates the argument string to upper-case. If you specify 
f, ED looks for an exact match. For example, Fcp/m 3 searches for CP/M 3 but 
fcp/m 3 searches for cp/m 3, and cannot find CP/M 3. 

If ED does not find a match for the string in the memory buffer, it issues the 

message. 



where the symbol # indicates that the search failed during the execution of an F 
command. 

The N Command 

The N command extends the search function beyond the memory buffer to include 
the source file. If the search is successful, it leaves the CP pointing to the first char- 
acter after the search string. The N command takes the form: 

nNstring 

where n is the occurrence of the string to be found. If no number is entered, ED 
looks for the next occurrence of the string in the file. The case of the N command 
has the same effect on an N command as it docs on an F command. Note that if you 
follow an N command with another ED command, you must terminate the string 
with a CTRL-Z. 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 6.6 Advanced ED Commands 

When an N command is executed, ED searches the memory buffer for the specified 
string, but if ED does not find the string, it docs not issue an error message. Instead, 
ED automatically writes the searched data from the buffer into the new file. Then 
ED performs a OA command to fill the buffer with unsearched data from the source 
file. ED continues to search the buffer, write out data, and append new data until it 
either finds the string or reaches the end of the source file. If ED reaches the end of 
the source file, ED issues the following message: 

BREAK "«" AT 

Because ED writes the searched data to the new file before looking for more data 
in the source file, ED usually writes the contents of the buffer to the new file before 
finding the end of the source file and issuing the error message. 

Note: you must use the H command to continue an edit session after the source file 
is exhausted and the memory buffer is emptied. 

The J (Juxtapose) Command 

The J command inserts a string after the search string, then deletes any characters 
between the end of the inserted string to the beginning of the a third delete-to string. 
This juxtaposes the string between the search and delete-to strings with the insert 
string. The J command takes the form: 

njsearch string'Zinsert string"Zde!ete-to string 

where n is the occurrence of the search string. If no number is specified, ED searches 
for the next occurrence of the search string in the memory buffer. In the following 
example, ED searches for the word "Dickinson", inserts the phrase "told a friend" 
after it, and then deletes everything up to the comma. 

1: »»r 

1; Emilv Dickinson saidt 

2: "I find ecstasy in liuins - 

3: the were of liuind 

Hi is Joy enough." 

1; «jDicf(inson"Z told a f riend'Z t 

li *01t 

1: Emily DjcKinson told a friend. 



S DIGITAL RESEARCH™ 



6.6 Advanced ED Commands CP/M 3 User's Guide _ 

If you combine this command with other commands, you must terminate the 
deleie-to string with a CTRL-Z or ESC, as in the following example. If an upper- — 
case J command letter is specified, ED looks (or upper-case search and delete-to 
strings and inserts an upper-case insert string. 

The J command is especially useful when revising comments in assembly language 
source code, as follows 

23G: SORT LXI H, SW JADDRESS TOGGLE SWITCH — 

23G: *J!'ZfiDDRESS SUITCH TOGGLE' Z-fZOLT 

23G: SORT LXI H. SW ;ADDRESS SWITCH TOGGLE 

23B: * — 

In this example, ED searches for the first semicolon and inserts ADDRESS SWITCH 
TOGGLE after the mark and then deletes to the <cr><lf> sequence, represented by _ 
CTRL-L. In any search string, you can use CTRL-L to represent a <cr><lf> when 
the phrase that you want extends across a line break. You can also use a CTRL-1 in 
a search string to represent a tab. 

Note: if long strings make your command longer than your screen line length, enter 
a CTRL-E to cause a physical carriage return at the screen. A CTRL-E returns the 
cursor to the left edge of the screen, but does not send the command line to ED. __ 
Remember that no ED command line containing strings can exceed 100 characters. 
When you finish your command, press the carriage return key to send the command 
to ED. 

The M {Macro) Command 

An ED macro command, M, can increase the usefulness of a string of commands. — 
The M command allows you to group ED commands together for repeated execu- 
tion. The M command takes the following form: 

nMcommand string , 

where n is the number of times the command string is to be executed. A negative 
number is not a valid argument for an M command, if no number is specified, the — 
special character # is assumed, and ED executes the command string until it reaches 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 6.6 Advanced ED Commands 

the end of data in the buffer or the end of the source file, depending on the com- 
mands specified in the string. In the following example, ED executes the four com- 
mands repetitively until it reaches the end of the memory buffer: 

1 ! *mfliviT}g'Z-GdiLiuini'Z01t 
2: "I find ecstasy in LiuinS - 
3: the mere sense of LivinS 



The terminator for an M command is a carriage return; therefore, an M command 
must be the last command on the line. Also, all charaaer strings that appear in a 
macro must be terminated by CTRL-Z or ESC. If a character string ends the com- 
mm, bined-command string, it must be terminated by CTRL-Z, then followed by a <cr> 
to end the M command. 

The execution of a macro command always ends in a BREAK "»" message, even 
when you have limited the number of times the macro is to be performed, and ED 
does not reach the end of the buffer or source file. Usually the command letter 
displayed in the message is one of the commands from the string and not M. 

To abort a macro command, press a CTRL-C at the keyboard. 

The Z (Sleep) Command 

Use the Z command to make the editor pause between operations. The pauses give 
you a chance to review what you have done. The Z command takes the following 
form: 



where n is the number of seconds to wait before proceeding to the next instruction. 

Usually, the Z command has no real effea unless you use it with a macro com- 
mand. The following example shows you how you can use the Z command to cause 
a brief pause each time ED finds the word TEXT in a file. 

fi>*mfliuin9'Z0ttl0z 



IS DIGITAL RESEARCH'- - 



6.6 Advanced ED Commands CP/M 3 User's Guide 

6.6.3 Moving Text Blocks 

To move a group of lines from one area of your data to another, use an X 
command to write the text block into a temporary LIB file, then a K command to 
remove these lines from their original location, and finally an R command to read 
the block into its new location. 

The X (Transfer) Command 

The X command takes the forms: 



nXfilespec'Z 

where n is the number of lines from the CP towards the bottom of the buffer that 
are to be transferred to a file. Therefore, n must always be a positive number. The 
nX command with no file specified creates a temporary file named X$$$$$$$.LIB. 
This file is erased when you terminate the edit session. The nX command with a file 
specified creates a file of the specified name. If no filetype is specified, LIB is assumed. 
This file is saved when you terminate the edit session. If the X command is not the 
last command on the line, the command must be terminated by a CTRL-Z or ESC. 
In the following example, just one hne is transferred to the temporary file: 

i! *X 

1: *t 

1: * Em ill- DicKinson saidf 

1 : *Ht 

l! *"I find ecstasy in livins - 



If no library file is specified, ED looks for a file named X$S$$$$S.L1B. If the file 
does not exist, ED creates it. If a previous X command already created the library 
file, ED appends the specified lines to the end of the existing file. 

Use the special character as the n argument in an X command to delete any file 
from within ED. 



- IBDTGITAL RESEARCH™ 



CP/M 3 User's Guide 



6.6 Advanced ED Commands 



The R (Read) Command 



The X command transfers the next n lines from the current line to a library file. 
The R command can retrieve the transferred lines. The R command takes the forms; 



R 
Rfilepsec 

If no filename is specified, X$$$$$$$ is assumed. If no 61etype is specified, LIB is 
assumed. R inserts the library file in front of the CP; therefore, after the file is added 
to the memory buffer, the CP points to the same character it did before the read, 
although the character is on a new line number. If you combine an R command with 
other commands, you must separate the filename from subsequent command letters 
with a CTRL-Z as in the following example where ED types the entire file to verify 
the read. 



*/?-ze«r 

"I find ecstasy in liuinS 
the mere sense of liuind 
is Joy enough*" 
Eitiily Dickinson saidi 



6.6.4 Saving or Abandoning Changes: £D Exit 

You can save or abandon editing changes with the following three commands. 

The H (Head of File) Command 

An H command saves the contents of the memory buffer without ending the ED 
session, but it returns to the head of the file. It saves the current changes and lets you 
reedit the file without exiting ED. The H command takes the following form: 



I I followed by a carriage return. 



W DIGITAL RESEARCH" 



6,6 Advanced ED Commands CP/M 3 User's Guide " 

To execute an H command, ED first finalizes the new file, transferring all lines 
remaining in the buffer and the source file to the new file. Then ED closes the new 
file, erases any BAK file that has the same file specification as the original source file, 
and renames the original source file filename, BAK. ED then renames the new file, 
which has had the filetype $$$, with the original file specification. Finally, ED opens "" 
the newly renamed file as the new source file for a new edit, and opens a new $$$ 
file. When ED returns the * prompt, the CP is at the beginning of an empty memory 
buffer. _ 

If you want to send the edited material to a file other than the original file, use the 
following command: 

fl>FD filesPBC differentfilesPBC 

If you then restart the edit with the H command, ED renames the file differentfile- ^ 
name.$$$ to differentfilename.BAK and creates a new file of differentfilespec when 
you finish editing. 

The O (Original) Command 

An O command abandons changes made since the beginning of the edit and allows 
you to return to the original source file and begin reediting without ending the ED "" 
session. The O command takes the form: 



followed by a carriage return. When you enter an O command, ED confirms that 
you want to abandon your changes by asking 

(Y/N>? 

You must respond with cither a Y or an N; if you press any other key, ED repeats 
the question. When you enter Y, ED erases the temporary file and the contents of the 
memory buffer. When the * prompt returns, the character pointer is pointing to the 
beginning of an empty memory buffer, just as it is when you start ED. 



m DIGITAL RESEARCH'" 



CP/M 3 User's Guide 



6.6 Advanced ED Commands 



The Q (Quit) Command 



A Q command abandons changes made s 
exits ED. The Q command takes the form: 



£ the beginning of the ED session and 



followed by a carriage return. 

When you enter a Q command, ED verifies chat you want to abandon the changes 
by asking 



You must respond with either a Y or an N; if you press any other key, ED repeats 
the question. When you enter Y, ED erases the temporary file, closes the source file, 
and returns control to CP/M 3. 

Note: you can enter a CTRL-Break or a CTRL-C to return control immediately to 
CP/M 3. This does not give ED a chance to close the source or new files, but it 
prevents ED from deleting any temporary files. 



6.7 ED Error Messages 

ED returns one of two types of error messages: an ED error message if ED cannot 
execute an edit command, or a CP/M 3 error message if ED cannot read or write to 
the specified file. An ED error message lakes the form: 



where x is one of the symbols defined in the following table and c is the command 
letter where the error occurred. 



m DIGITAL RESEARCH'" 



6.7 ED Error Messages CP/M 3 User's Guide 

Table 6-4. ED Error Symbols 



Symbol Meaning 



Search failure. ED cannot find the string specified in a F, S, or N 
command. 

Unrecognized command letter c. ED does not recognize the indi- 
cated command letter, or an E, H, O, or Q command is not alone 
on its command Hne. 

No. LIB file. ED did not find the LIB file specified in an R command. 

Buffer full. ED cannot put anymore characters in the memory buffer, 
or string specified in an F, N, or S command is too long. 

Command aborted. A keystroke at the keyboard aborted com- 
mand execution. 

File error. Followed by either disk FULL or DIRECTORY FULL. 



The following examples show how to recover from common editing error condi- 
tions. For example 

BREAK ">" AT A 

means that ED filled the memory buffer before completing the execution of an A 
command. When this occurs, the character pointer is at the end of the buffer and no 
editing is possible. Use the OW command to write out half the buffer or use an O or 
H command and reedit the file. 

BREAK "«" AT F 

means that ED reached the end of the memory buffer without matching the string in 
an F command. At this point, the character pointer is at the end of the buffer. Move 
the CP with a B or n; line number command to resume editing. 

BREAK "F" AT F 
DISK FULL 



LktSEARCH ■' 



CP/M 3 User's Guide 6.7 ED Error Messages 

Use the OX command to erase an unnecessary 6le on the disk or a B#Xd:buffer.sav 
command to write the contents of the memory buffer onto another disk. 

BREftK "F" AT n 
DIRECTORY FULL 

Use the same commands described in the previous message to recover from this file 
error. 

The following table defines the disk file error messages ED returns when it cannot 
read or write a file. 



Table 6-5. ED Dislcette File Error Messages 



Message Meaning 



CP/M Error on d: Read/On 1 / Fi 1 e 
BDDB Function = NN Fi 1 e = FILENAME . TYP 

Disk d: has Read-Only attribute. This occurs if a different disk 
has been inserted in the drive since the last cold or warm boot. 



*» FILE IS READ ONLY *» 



The file specified in the command to invoke ED has the R/O 
attribute, ED can read the file so that the user can examine it, 
but ED cannot change a Read-Only file. 



End of Section 6 



DIGITAL RESEARCH'" - 



Appendix A 
CP/M 3 Messages 



Messages come from several different sources. CP/M 3 can display error messages 
when the Basic Disk Operating System (BDOS) returns an error code. CP/M 3 can 
also display messages when there are errors in command lines. Each utility supplied 
with CP/M 3 has its own set of messages. The following table lists CP/M 3 messages 
and utility messages. If you are running an application program, you might see 
messages other than those listed here. Check the application program's documenta- 
tion for explanations of those messages. 

The messages in Table A-1 might be preceded by ERROR:. Some of them might 
also be preceded or followed by the filespec of the file causing the error condition. 
Sometimes the input line is flagged with an up arrow | , to indicate the character 
that caused the error. In this case, the message. Error at the ', precedes the 
appropriate error message. Some of the messages are followed by an additional line 
preceded by INPUT;, OPTION:, or DRIVE: followed by the applicable error message. 



Table A-1. CP/M 3 Messages 



Message Meaning 



Assign a password to this file. 

SET, A password mode has been seleaed for this file but no 
password has been assigned. 

Auxiliary deulce redirection not implemented! 

GET and PUT. AUXIN and AUXOUT cannot be redirected to 
a file. 

Bad character* re-enter 

GENCPM. The character entered was not a number. 



m DIGITAL RESEARCH™ 



A CP/M 3 Messages CP/M 3 User's Guide 

Table A-1. (condoued) 



Message Meaning 



Bad close* 



SAVE, An error occurred during the attempt to close the file, 
probably because the file is write-protected. 



Bad Logical Deuice Ass i 9nmeri t S 



DEVICE. Only the foUowing logical devices are valid: CONIN:, 
CONOUT:, AUXIN:, AUXOUT:, LST:. 



BAD PARAMETER 



PIP. You entered an illegal parameter in a PIP command. Retype 
the entry correctly. 



Bad passwordt 

RENAME. The password supplied by the user is incorrect. 



BanK one not allowed. 



GENCPM. Bank 1 cannot be defined as available during sys- 
tem generation. 



Baud rale cannot be set for this deuicet 

DEVICE. Only physical devices that have the SOFT-BAUD 
attribute can have their baud rates changed. To check the attri- 
butes of the physical device, type DEVICE physical-dev. 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



A CP/M 3 Messages 



Table A-1. (continued) 



Message 



Meaning 



ED. "x" is one of the symbols described below and c is tlie 

command letter being executed when the error occurred. 

« Search failure. ED cannot find the string specified in an 

F, N, or S command, 
? Unrecognized command letter c. ED does not recognize 

the indicated command letter, or an E, H, O, or Q com- 
mand is not alone on its command line. 
The file specified in an R command cannot be found. 

> Buffer full. ED cannot put any more characters in the 

memory buffer, or the string specified in an F, N, or S 

command is too long. 
E Command aborted. A keystroke at the console aborted 

command execution. 
F Disk or directory full. This error is followed by either 

the disk or directory full message. Refer to the recovery 

procedures listed under these messages. 



CftNNDT CLOSE: 

Cannot close file. 

CANNDT CLOSE FILE. 

CANNOT CLOSE DESTINATION FILE - 



GENCOM, HEXCOM, LIB-80'", LINK-80, MAC, PIP, RMAC, 
SUBMIT. An output file cannot be closed. This can occur if the 
disk is removed before the program terminates. 



Cannot delete file> 



GENCOM. CP/M cannot delete a file. Check to see il 
file is Read-Only or password-protected. 



e DIGITAL RESEARCH'- - 



A CP/M 3 Messages CP/M 3 User's Guide -> 

Tabic A-1. (continued) 



Cannot haue both create and access time stampst 

SET. CP/M 3 suppons either create or access time stamps, but 
not both. 



Cannot label a drive with a file referenced. 

SET. SET does not allow mixing of files and drives. 



CANNOT OPEN SOURCE FILE 

HEXCOM. The HEX file is not on the specified dnve(s). 



Cannot redirect froMBIOS. 



GET, PUT. This message is displayed as a warning only if the 
system has an invalid BIOS. 



Cannot set both RO and RW . 

SET. A file cannot be set to both Read-Only and Read-Write. 



Cannot set both SYS and DIR. 

SET. A file cannot be set to both SYS and DIR. 



CAN'T DELETE TEMP FILE 



PIP. A temporary $$$ file already exists which is Read-Only. 
Use the SET command to change the attribute to Read- Write, 
then erase it. 



- m DIGITAL RESEARCH'" 



"1 

n CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued} 



Message Meaning 



CHECKSUM ERROR. 
ChecKsum error 



HEXCOM, PIP, A hex record checksum error was encoun- 
tered. The hex record that produced the error must be cor- 
reaed, probably by recreating the hex file. 



Close error 



XREF. This message is preceded by the filename. XRF. The disk 
might have been removed before the program terminated. 



Close operation failed. 



COPYSYS, There was a problem in closing the file at the end 
of the file copy operation. 



Closing file HELP. DAT 
Closing file HELP.HLP 



HELP. HELP encountered error while processing the HELP.DAT 
or the HELP.HLP file. 



COM file found and NULL option. 



GENCOM. The NULL option implies that no COM file is to 
be loaded, just the RSXs. 



■ COM file re<iui red 



DIR, ERASE, RENAME, TYPE. Options in the built-in com- 
mand line require support from a transient COM file that 
CP/M 3 cannot find on disk. 



CDHMON ERROR; 

LINK-80, An undefined common block has been selected. 



m DIGITAL RESEARCH'* 



A CP/M 3 Messages CP/M 3 User's Guide 

Table A-I. (continued] 



Meaning 



CORRECT ERROR , TYPE RETURN DR CTRL-2 



PIP. A hex record checksum was encountered during the trans- 
fer of a hex file. The hex file with the checksum error should 
be corrected, probably by recreating the hex file. 



CPMLDR error: failed to open CPM3.SYS 

CPMLDR. The system file CPM3.SYS is missing. 



CPMLDR error: failed to read CPM3.SYS 

CPMLDR. An error occurred while reading CPM3.SYS. 



CP/M Error on d: OisK I/O 

BDOS Function = kx File = filespec 



CP/M displays the preceding message if the disk is defective or 
improperly formatted (wrong density). 



CP/M Error on d: Inualid Driue 
BDOS Function = kx File = filespec 



CP/M 3 displays the preceding message when there is no disk 
in the drive, the drive latch is open, or the power is off. It also 
displays the message when the specified drive is not in the 

system. 



CP/M Error on 6: Read/Only DisK 
BDOS Function = xk File = filespec 



CP/M 3 does not allow you to erase, rename, update, or set 
attributes of a file residing in a Read-Only drive. Use the SET 
command to set the drive attribute to Read- Write. 



m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



A CP/M 3 Messages 



Tabic A-1. (continued) 



Message 



Meaning 



CP/M Error on d: Read/Only File 
BDOS Function = mk File = filespec 



CP/M 3 does not allow you to erase, rename, update, or set 
attributes of a file that is Read-Only. Use the SET command to 
set the file attribute to Read-Write, 



Date and Time StawpinS Inactive. 



DIR. The DATE option was specified, but the disk directory 
has not been initialized with date/time stamping. 



DESTINATION IS R/0 » DELETE (Y/N)? 



PIP. The destination file specified in a PIP command already 
exists and it is Read-Only. If you type Y, the destination file is 
deleted before the file copy is done. If you type N, PIP displays 
the message * *NOT DELETED* * and aborts the copy 
operation. 



Oeuice Reassignment Not Supported. 
Enter new assignment or hit RETURN. 



DEVICE. A device assignment is invalid. 



Directory already re-formatted. 

INITDIR. The directory already has date/time stamping. 



m DIGITAL RESEARCH- 



A CP/M 3 Messages 



CP/M 3 User's Guide 



Tabic A-1, (continued) 



Message 



Meaning 



Di recto ry full 
DIRECTORY FULL 



ED, There is not enough directory space for the file being writ- 
ten to the destination disk. You can use the OXfilespec com- 
mand to erase any unnecessary files on the disk without leaving 
the editor, 

SUBMIT. There is not enough directory space on the tempo- 
rary file drive to write the temporary file used for processing 
SUBMIT files. Use the SETDEF command to determine which 
drive is the temporary file drive. Use the ERASE command to 
erase unnecessary files or set the temporary file drive to a dif- 
ferent drive and retry. 

LIB-80, LINK-80. There is no direaory space for the output or 
intermediate files. Use the ERASE command to remove unnec- 
essary files. 

GENCPM. There is no directory space for CPM3.SYS. 
HEXCOM. There is no directory space for the output COM 
file. 



Directcrv needs to be reformatted for date/time stamps* 

SET. A date/time option was specified, but the directory has 

not been initialized for date/time stamping. Use the INITDIR 
command to initialize the directory for date/time stamping. 



ED. There is not enough disk space for the output file. This 
error can occur on the E, H, W, or X commands. If it occurs 
with X command, you can repeat the command prefixing the 
filename with a different drive, 



!9 DIGITAL RESEARCH"" 



CP/M 3 User's Guide 



A CP/M 3 Messages 



Table A-1. (continued] 



Meaning 



DISK READ 

DISK REftD ERROR: 

DisK read errors filespec 

DISK READ ERROR - filespec 



GENCPM, HEXCOM, LIB-8 
specified cannot be read. 



, PIP. The disk file 



DISK UIRITE. 

Di sK N rite Error 

DISK WRITE ERROR: 

DISK WRITE ERROR - filespec 



HEXCOM, LIB-80, LINK-80, PIP, SUBMIT. A disk write 
operation cannot be successfully performed probably because 
the disk is full. Use the ERASE command to remove unneces- 
sary files. 



Do you want another file? (Y/N) 



PUT. Enter Y to icdirect output to an additional file. Other- 
wise, enter N. 



Drive defined twice in search path 



SETDEF. A drive can be specified only once in the search path 
order. 



Driue Read On 1 / 



ERASE, RENAME. The specified file is on a Rcad-Only dri- 
and cannot be erased or renamed. 



Driue specified has not been definedi 



GENCPM. The drive specified has not been defined yet. Buffer(s) 
have not been allocated for the drive. 



m DIGITAL RESEARCH- - 



A CP/M 3 Messages CP/M 3 User's Guide 

Tabic A-1. (continued) 



Message 


Meaning 


1 


Dupliciite RSK in header. Replacing old by neu. 
Thi5 file was not used. 

GENCOM. The specified RSX is already attached to the COM 

file. The old one is discarded. 


Duplicate input RSX. 

GENCOM. Two or more RSXs of the same 
GENCOM uses only one of the RSXs. 


name are specified. 


Equals ( = ) delimiter Missing at lineNN. 

GENCPM. The equal sign is missing in the 


specified line. 


END OF 


FILE . 'Z . ? 

PIP encountered an unexpected end-of-file 
transfer. 


during a HEX file 


End of 


line expected . 

DEVICE, GET, PUT, SETDEF. The command typed does not 
have any further parameters. An end-of-line was expected. Any 
further characters on the line were ignored. 


Error 


at end of line: 

DEVICE, GET, PUT, SETDEF. The error detected occurred at 
the end of the input line. 


Error 


on line nnnnns 

SUBMIT. The SUBMIT program displays its messages in the 
preceding format, where nnnnn represents the line number of 
the SUBMIT file. Refer to the message following the line num- 
ber for explanation of the error. 



-■ SIDIGITAI. RESEARCH" 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued) 



Meaning 



FILE ERROR 



ED. Disk or directory is full, and ED cannot write anything 
more on the disk. This is a fatal error, so make sure there is 
enough space on the disk to hold a second copy of the file 
before invoking ED. 



File already existsi Delete it? <Y/N) 
file al ready exists, delete (Y/N)? 

PUT. Enter Y to delete the file. Otherwise the program 

terminates. 

RENAME. The above message is preceded by fiiespec. You 

have asked CP/M 3 to create or rename a file using a file 

specification that is already assigned to another file. Either delete 

the existing file or use another file specification. 



File cannot fit into GENCPM buffer; filenahie.SPR 

GENCPM. There is not enough memory to generate a system. 



File eKistsr erase : 



ED. The destination filename already exists when you are plac- 
ing the destination file on a different disk than the source. It 
should be erased or another disk selected to receive the output 
file. 



FILE IS READ/ONLY 
File is Read Only 



ED. The file specified in the command to invoke ED has the 

Read-Only attribute. ED can read the file so that you can 

examine it, but ED cannot change a Read-Only file. 

PUT. The file specified to receive the output is a Read-Only 

file. 



HDIGITAL RESEARCH" 



A CP/M 3 Messages CP/M 3 User's Guide — 

Tabic A-1. (continued) 



Message Meaning 



FILE NftME ERROR: 

LIB-80. The form of a source filename is invalid. 



File not found . 

FILE NOT FOUND - filespec 



DUMP, ED, GENCOM, GET, PIP, SET. An input file that you 
have specified does not exist. Check that you have entered the 
correct drive specification or that you have the correa disk in 
the drive. 



First submitted file must be a COM file, 

GENCOM. A COM file is expected as the first file in the com- 
mand tail. The only time GENCOM does not expect to see a 
COM file in the first position of the command tail is when the 
NULL option is specified. 



FIRST COMMON NOT LARGEST: 



LINK-80. A subsequent COMMON declaration is larger than 
the first COMMON declaration for the indicated block. Check 
that the files being linked are in the proper order, or that the 
modules in a library arc in the proper order. 



HELP. DAT not on current driye. 

HELP. HELP cannot find HELP.DAT file to process. 



Illegal command tail> 

DIR. The command line has an invalid format or option. 



m DIGITAL RESEARCH™ 



n CP/M 3 User's Guide A CP/M 3 Messages 

_ Table A-1. (continued) 



Message Meaning 



Illegal Fo rmat lvalue . 



DIR, Only SIZE and FULL options can be used for display 
formats. 



nie9al Global /Local Driue Spec Mi Kin 9. 



DIR. Both a filespec with a drive spjedfier and the DRIVE option 
appears in the command. 



Illegal f i lename . 

SAVE. There is an error in the filespec on the command line. 



Illesal Option or Modifier. 

DIR. An invahd option or abbreviation was used. 



Illegal date/time specification. 

DATE, Date/time format is invalid. 



Incorrect file specifioation, 

RENAME. The format of the filespec is invalid. 



INDEX ERRQR: 

LINK-80. The index of an IRL contains invalid information. 



Insufficient Memory 
INSUFFICIENT MEMORY: 



GET, LINK-80, PUT, SUBMIT. There is not enough memory 
to allocate buffers, or there are too many levels of SUBMIT 
nesting. 



! I m DlCtTAL RESEARCH" 



A CP/M 3 Messages CP/M 3 User's Guide 

Tabic A-1. (continued) 



Message 


Meaning 


Inual 


d ASCII character 




SUBMIT. TTie SUBMIT file contains an invalid character (OFFH). 


Inval 


6 character at line NN . 




GENCPM. The character must be a number. 


Inual 


d coBifnand. 




GET and PUT. The string or substring typed in the command 
line was not recognized as a valid command in the context 

used. 


Inual 


d delimiter. 




DEVICE, GET, PUT, SETDEF. The delimiter, [ 1 , = or space, 
— was not valid at the location used. For example, a [ was 
used where an = should have been used. 


INUfiLID DESTINATION: 




PIP. An invalid drive or device was specified. 


INUALID DIGIT - f ilespfic 




PIP. An invalid hex digit has been encountered while reading a 
hex file. The hex file with the invalid hex digit should be cor- 
rected, probably by recreating the hex file. 


Inual 


Id driue. 




SETDEF. The specified drive was not a valid drive. Drives rec- 
ognized by SETDEF are * [default drive) and A to P. 




GENCPM, TYPE. Valid drives are A to P. 



RESEARCH- 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1 . (continued) 



Message Meaning 



Invalid drive ignored at line NN> 

GENCPM. Valid drives are A to P. 



Invaliddriuename (UseAiGiGt 



COPYSYS, GENCPM. Only drives A, B, C and D are valid 
destination drives for system generation. 



Inualid File. 

INVALID FILENAME 

Ini^alid file name. 

Inval id Fi lename . 

Invalid file specification. 



ED, ERASE, GENCOM, GET, PIP, PUT, SET, SUBMIT, TYPE. 
The filename typed does not conform to the normal CP/M 3 
file naming conventions. 



INVALID FORMAT 



PIP. The format of your PIP command is illegal. See the 
description of the PIP command. 



INUALID HEX DIGIT. 



HEXCOM. An invalid hex digit has been encountered while 
reading a hex file. The hex file with the invalid hex digit should 
be corrected by recreating the hex file. 



Invalid numbe r ■ 



DEVICE. A number was expected but not found, or the num- 
ber was out of range; numbers must be from to 255. 



1 DTC;rTAL RESEARCH'- 



A CP/M 3 Messages 



CP/M 3 User's Guide — 



Table A-1. (continued) 



Meaning 



Iny al id OPt i on , 



DEVICE and GET. An option was expected and the string 

found was not a device option or was not valid in the context 

used. 

SETDEF. The option typed in the command Hne is not a valid 

option. Valid options are DISPLAY, NO DISPLAY, NO PAGE, 

ORDER, PAGE, TEMPORARY. 



Inualid option oriiiodifiert 

DIR, GET, PUT. The option typed is not a valid option. 



INUALID PARAMETER: 



MAC, RMAC. An invalid assembly parameter was found in 
the input line. The assembly parameters are printed at the con- 
sole up to the point of the error. 



Inualid parameter yariable at line UU. 

GENCPM. The parameter variable does not exist. Check 



INVALID PASSWORD 

Ini^alid password or passwords not allowed. 



ED, PIP. The specified password is incorrect, or a password 
was specified, but the file is not pass word -protected. 



Inualid phfsical deuice. 



DEVICE. A physical device nam 
in the command string does i 
device name in the system. 



was expected. The name found 
Dt correspond to any physical 



m DIGITAL RESEARCH" 



n CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued) 



Message Meaning 



INUftLID REL FILE: 



LINK-80. The file indicated contains an invalid bit pattern. 
Make sure that a REL or IRL file has been specified. 



Inval id RSX type . 

GENCOM. Filctype must be RSX. 



Inyalid SCB offset , 



GENCOM. The specified SCB is out of range. The SCB offset 
range is 00H-64H. 



INVALID SEPARATOR 



PIP. You have placed an invalid character for a separator 
between two input fill 



INVALID SOURCE 



PIP. An invalid drive or device was specified. AUX and CON 
are the only valid devices. 



Invalid type for ORDER option. 



SETDEF. The type specified in the command line was not COM 
or SUB. 



Inyalid SYM file format 

XREF. The filename.SYM file input to XREF is invalid. 



INVALID USER NUM5ER 



PIP. You have specified a user number greater than 15. User 
numbers are in the range to 15. 



il DIGITAL RESEARCH'" 



A CP/M 3 Messages CP/M 3 User's Guide 

Table A-1. {continued) 



Inualid wildcard. 



RENAME. The filespec contained an invalid wildcard 
specification. 



Invalid wild card in the FCB nawe or type field. 

GENCOM. GENCOM does not allow wildcards in filespecs. 



LDflD ADDRESS LESS THAN 100. 

HEXCOM. The program origin is less than lOOH. 



MAIN MODULE ERROR: 

LINK-80. A second main module was encountered. 



Make error 

XREF. There is not more directory space on the specified drive. 



Memory conflict - car^not trim segment. 

GENCPM. The defined memory segment overlaps another 
segment. 



Memory conflict - seSinent trimmed. 



GENCPM. The defined memory segment overlaps with other 
segments. 



MEMORY OyERFLQW: 



LINK-80. There is not enough memory to complete the link 
operation. 



- 15 DIGITAL RESEARCH™ 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued) 



Messag 


e Meaning 






Minimum number of buffers is 1. 








GENCPM. The first drive must have at least one buffer defined. 


Miss 


n3 Delimiter or Unrecognized Option. 








ERASE. The ERASE command line format is 


invahd. 




Miss 


na parameter oariable at line NN. 

GENCPM. The line is missing a variable nam 


e. 




Miss 


nd left parenthesis . 








GENCOM. The SCB option must be enclosed by 
parenthesis. 


a left 


Missins rishl parenthBsiS4 








GENCOM. Tbe SCB option is not enclo 
parenthesis. 


cd with a 


right 


Miss 


ns SCB value. 

GENCOM. The SCB option requires a value. 






More 


than four drives specified. 








SETDEF. More than four drives were specified for the 
search chain. 


drive 


MULTIPLE DEFINITION: 








LINK-80. The specified symbol is defined in 
the modules being linked. 


■note than 


aneof 



n - 



DIGITAL RESEARCH" 



A CP/M 3 Messages 

Table A-1. {continiied) 



Message 



USER. You specified a number greater than fifteen for a user 
area number. For example, if you type USER 18, the screen 
displays 18?. 



No directory label exists. 



SHOW. The LABEL option was requested but the disk has no 

label. 



No directory space 
NO DIRECTORY SPACE ■ 



COPYSYS, GENCOM, MAC, PIP, RMAC, AND SAVE. There 
is not enough direaory space for the output file. Use the ERASE 
command to remove unnecessary files on the disk and try again. 



No d i sK space . 



SAVE. There is not enough space on the disk for the output 
file. Use the SHOW command to display the amount of disk 
space left and use the ERASE command to remove unnecessary 
files from the disk, or use another disk with more file space. 



No file 

NO FILE: 

NO FILE - f ilespec 



DIR, ERASE, LlB-80, LINK-80, PATCH, PIP, RENAME, TYPE. 
The specified file cannot be found in the specified drive[s). 



No HELP.HLP file on the default drive. 

HELP. The file HELP.HLP must be on the default drive. 



O DIGITAL RESEARCH™ 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (conrinued) 



Message Meaning 



NO INPUT FILE PRESENT ON DISK 

DUMP, The file you requested does not exist. 



There is not enough memory available for loading the specified 
program. 



No modifier for this optiont 

GENCOM. A modifier was specified but none is required. 



NO MODULE: 

LIB-80. The indicated module cannot be found. 



No more space in the header forRSXs or SCB 
initialization. 

GENCOM. The header has room for only 15 entries, or the 
combination of RSXs and SCBs exceed the maximum. 



No options specified. 

SET. Specify an option. 



No PRN file. 



XREF. The file filename. PRN is not present on the specified 
drive. 



No Reco rds Ex i st 

DUMP. Only a directory entry exists for the file. 



i DIGITAL RESEARCH" 



A CP/M 3 Messages CP/M 3 User's Guide 
Table A-1. (continued) 



Message 


Meaning 




No source f 


lie on disK. 






COPYSYS. The file CPM3.SYS is 


not on the disk specified. 


ND SOURCE FILE PRESENT! 






MAC, RMAC. The source file cannot be found on the specified 

drive. 


NO SPACE 








SAVE. There is no space in the 
written. 


direaory for the file being 


No 'SUB' f i 


le found. 






SUBMIT. The SUB file typed in 
found in the drive search process 


the command line cannot be 


No such f il 


e to rename. 






RENAME. The file to be renamed does not exist on the speci- 
fied drive(s). 


Nq SYM file 








XREF. The file filename .SYM i 
drive. 


not present on the specified 


NON-SYSTEM FILE(S) EXIST 






DIRS. If nonsystem (DIR) files 
DIRS displays this message. 


reside on the specified drive. 



- H DIGITAL. RESEARCH™ 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued) 



Message 


Meaning 






Nat enough a 
Not Enough M 
Not Enouah M 


Mailable memory, 
emo ry f or So n . 








DIR, INITDIR. There is no 
buffers. 


t enough memory for data or sort 


Not enouah room in directory. 








INITDIR. There is not enc 
allow for the date and time 


ugh remaining direaory space 
extension. 


to 


NOT FOUND 










PIP. PIP cannot find the specified file. 




Not renamed 


f i lespec read only . 








RENAME. The specified fil 
Read-Only. 


e cannot be renamed because i 


is 


OPEN FILE NONRECOyERfiBLE 








PIP. A disk has the wrong format or a bad sector. 




Option only 


for drives. 








SET. The specified option is 


not valid for files. 




Option requ 


res a file reference . 








SET. The specified option requires a filespec. 




Out of data space. 








COPYSYS. The destination drive ran out of space during 
transfer of the CPM3.SYS file. 


the 



pn 

' J m DICTTAL RESEARCH" 



A CP/M 3 Messages CP/M 3 User's Guide 

Table A-1. (continued) 



Message Meaning 



Qptions not grouped together. 

DIR. Options can only be specified within one set of brackets. 



DutPUt File Exists * Erase it. 

The output file specified must not already exist. 



DUTPUT FILE READ ERROR: 



MAC, RMAC. An output file cannot be written properly, 
probably because the disk is full. Use the ERASE command to 
delete unnecessary files from the disk. 



OUERLflPPING SEGMENTS! 



LINK-80. LINK-80 attempted to write a segment into memory 
already used by another segment. 



Pa9e and nopaSe option selected* 
No pade in effect. 



SET. The preceding options are mutually exclusive. 



Paramete r Error 



SUBMIT. Within the SUBMIT file of type SUB, valid parame- 
ters are $0 through $9. 



Password Error* 

DUMP, ERASE, GENCOM, TYPE. The password is 

Physical Deuice Does Not Exist, 

DEVICE. The specified physical device is not defined in the 
system. 

11 DIGITAI, RESEARCH'- 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued) 



I Message Meaning 



Possible incompatible disK forinat< 



COPYSYS. The system disk and the output disk have different 
formats. 



PROGRAM INPUT IGNORED. 



SUBMIT. This message is preceded by "WARNING". The 
SUBMIT file contains a line with <, and the program does not 
require additional input. 



PUT. This prompt occurs when a program requests input while 
running a PUT FILE [NO ECHO] command. 



PUT ERROR: FILE ERASED. 

PUT. The PUT output file was erased and could not be closed. 



QUIT NOT FOUND 



PIP. The string argument to a Q parameter was not found in 
your input file. 



RandDM Read 



SUBMIT. An error occurred when reading the temporary file 
used by the SUBMIT command. 



Read only. 

GENCOM, SET. The drive or file specified is write-protected. 



Read e r ro r 



TYPE. An error occurred when reading the file specified in the 
TYPE command. Check the disk and try again. 



IS DIGITAL RESEARCH'" 



A CP/M 3 Messages CP/M 3 User's Guide 

Table A-1. (continiicd) 



Meaning 



ReadinSfile: filespec 



GENCPM. An error occurred while attempting to read the file 
specified by filespec. 



Reading file HELP.HLP 
Readins HELP.HLP index 



HELP. An error occurred while reading HELP.HLP. Copy the 
HELP.HLP file from the system disk. 



RECORD TOD LONG 



PIP. A HEX record exceeds 80 characters in a file being copied 
with the [H] option. 



Requires CP/M 3.0 or hisher. 



DATE, DEVICE, DIR, ERASE, GENCOM, HELP, INITDIR, 
PIP, SET, SETDEF, SHOW, RENAME, TYPE. This version of 
the utility must only be run under CP/M 3.0 or higher. 



PIP. The destination drive is set to Read-Only and PIP cannot 
write to it. 



PIP. The destination file is set to Read-Only and PIP 



So rt StacK Due rf low 

DIR. There is not enough memory available for the sort stack. 



- PDIGITAL RESEARCH'" 



i-t CP/M 3 User's Guide A CP/M 3 Messages 

Tabic A-1. (continued) 



Message Meaning 



Source file is incomplete. 



GENCPM. GENCPM cannot use your CP/M 3 system source 
file. 



SOURCE FILE READ ERROR: 

MAC, RMAC. The source file cannot be read properly by MAC. 



SOURCE FILENAME ERROR: 

MAC, RMAC. The form of the source filename is invalid. 



START NOT FOUND 



PIP. The string argument to an S parameter cannot be found ii 
the source file. 



Sfmbol Table oyerf low 

XREF. No space is available for an attempted symbol allocation. 



Symbol Table reference ouerflow 



XREF. No space is available for an attempted symbol reference 
allocation. 



SYNTAX ERROR: 

LIB. The LIB-80 command is not properly formed. 



Too many entries in Index Table. 
Not enough memo rv 



HELP. There is not enough memory available to hold the topic 
table while creating HELP.HLP. 



m DIGITAL RESEARCH'" 



A CP/M 3 Messages CP/M 3 User's Guide 

Table A-1. (continued) 



Meaning 



Topic: 

KMKKKK 

Not found , 



HELP. The topic requested does not exist in the HELP.HLP 
file. HELP displays the topics available. 



Total file size exceeds GaK. 

GENCOM. The output file exceeds the maximum allowed. 



Try 'PftGE' or 'NO PAGE' 

TYPE. The only valid option is PAGE or NO PAGE. 



Unable to allocate Data deblDcKin9 buffer space. 

GENCPM. There is not enough space leh in generated system 
to allocate a data deblocking buffer. 



Unable to allocate Dir deblocKinS buffer space. 

GENCPM, There is not enough space left in generated system 
to allocate a directory deblocking buffer. 



I allocate space for hash table. 

GENCPM. There is not enough contiguous memory to allocate 
space for the hash table in the generated system. 



Unable to close HELP. DAT. 
Unable to close HELP.HLP. 



HELP. An error occurred while closing file HELP.HLP or 
HELP.DAT. There might not be enough disk or directory space 
on the drive. 



- IIBIGTTAL RESEARCH" 



CP/M 3 User's Guide A CP/M 3 Messages 

Table A-1. (continued) 



Unable to find file HELP.HLP. 



HELP. HELP requires HELP.HLP file to operate. Copy it to 
your default drive from your CP/M 3 system disk. 



Unable to MaKe HELP. DAT. 
Unable to MaKe HELP.HLP. 



HELP. There is not enough space on the disk for HELP.HLP 
or HELP.DAT, or the files are Read-Only. 



Unable to open: filename. SPR 



GENCPM. The file specified cannot be found on the default 
drive. 



UNBALANCED MAGRO LIBRARY. 



MAC, RMAC. A MACRO definition was started within a macro 
library, but the end of the file was found in the library before 

the balancing ENDM was encountered. 



UNDEFINED START SYMBOL: 



LINK-80. The symbol specified with the G switch i: 
in any of the modules being linked. 



UNDEFINED SYMBOLS: 



LINK-80. The symbols following this message are referenced 
but not defined in any of the modules being linked. 



UNEXPECTED END OF HEX FILE - filespec 



PIP. An end-of-file was encountered before a termination hex 
record. The hex file without a termination record should be 
corrected, probably by recreating the hex file. 



A CP/M 3 Messages CP/M 3 User's Guide 

Tabic A-1. (continued) 



Message 


Meaning 






Un recoanized 


drive. 








SHOW. The specified drive i 
P. 


not vaHd. VaHd drives are A to 


UNRECOGNIZED 


ITEM: 








LlNK-80. An unfamiliar bit 
ignored by LINK- 80. 


pattern has been scanned and 


Unrecognized 


input. 








SHOW. The SHOW comman 


d Hne has an invalid forma 


.. 


Un recoSnized 


option . 








GENCOM and SHOW. An option typed in the comma 
is not vaiid for the command. 


nd line 


USER ABORTED 










PIP. You stopped a PIP operation by pressing CTRL-C. 




VERIFY ERROR 


- filespec 








PIP. When copying with the V option, PIP found a difference 
when rereading the data just written and comparing it to the 
data in its memory buffer. 



g DIGITAL RESEARCH'" 



n 



n CP/M 3 User's Guide A CP/M 3 Messages 

_ Tabic A-1. (continued) 

Message Meaning 



Write error 



XREF. This message is preceded by filename. XRF and indicates 
that no disk space is available, or no directory space exists on 
the specified drive. 



Write protected? 



COPYSYS, The drive or disk to which the system is to be 
written is Read- Only. 



Writingfiles filespec 



GENCPM, HELP. An error occurred while attempting to v 
the file specified by filespec. 



Wrong Password « 

SET. The specified password is incorrect or invaHd. 



Zero length sedment not atlowed« 

GENCPM. A memory segment cannot have zero length. 



OFFFFH is an inualid ualue in the DPHdi rectory BCB 
add ress field . 

GENCPM. This value is allowed only in the DTABCB field. 



SID. SID has encountered an error. 



n End of Appendix A 



n 



ra DIGITAL RESEARCH" 



] 

n 

1 
1 



Appendix B 
ASCII and Hexadecimal Conversions 



ASCII stands for American Standard Code for Information Interchange. The code 
contains 96 printing and 32 non-printing charaaers used to store data on a disk. 
Table B-1 defines ASCII symbols, then Table B-2 lists the ASCII and hexadecimal 
conversions. The table includes binary, decimal, hexadecimal, and ASCII conversions. 





Table B-1. 


ASCn Symbols 




Symbol 


1 Meaning | 


Symbol 


Meaning 


ACK 


acknowledge 


FS 


file separator 


BEL 


bell 


GS 


group separator 


BS 


backspace 


HT 


horizontal tabulation 


CAN 


cancel 


LF 


line-feed 


CR 


carriage return 


NAK 


negative acknowledge 


DC 


device control 


NUL 


null 


DEL 


delete 


RS 


record separator 


DLE 


data link escape 


SI 


shift in 


EM 


end of medium 


SO 


shift out 


ENQ 


enquiry 


SOH 


start of heading 


EOT 


end of transmission 


SP 


space 


ESC 


escape 


STX 


start of text 


ETB 


end of transmission 


SUB 


substitute 


ETX 


end of text 


SYN 


synchronous idle 


FF 


form-feed 


US 


unit separator 






VT 


vertical tabulation 



n DIGITAL RESEARCH™ 



B ASCn and Hexadecimal Conversions 



CP/M 3 User's Guide 





Table B-2. 


ASCII Conversion Table 






Binary 


Decimal 


Hexadecimal 




Ascj; 


0000000 








NUL 




0000001 


1 


1 


SOH 


(CTRL-A) 


0000010 


2 


2 


STX 


(CTRL-B) 


0000011 


3 


3 


ETX 


(CTRL^C) 


0000100 


4 


4 


EOT 


(CTRL-D) 


0000101 


S 


5 


ENQ (CTRL-E) 


0000110 


6 


6 


ACK (CTRL-F) 


0000111 


7 


7 


BEL 


(CTRL-G) 


0001000 


8 


S 


BS 


(CTRL-H) 


0001001 


9 


9 


HT 


(CTRL-I) 


0001010 


10 


A 


LF 


(CTRL-J) 


0001011 


11 


B 


\T 


(CTRL-K) 


0001100 


12 


C 


FF 


(CTRL-L) 


0001101 


13 


D 


CR 


(CTRL-M) 


0001110 


14 


E 


SO 


(CTRL-N) 


0001111 


IS 


T 


SI 


(CTRL-O) 


0010000 


16 


10 


DLE 


(CTRL-P) 


0010001 


17 


11 


DCl 


(CTRL-Q) 


0010010 


18 


12 


DC2 


(CTRL-R) 


0010011 


19 


13 


DC3 


(CTRL-S) 


0010100 


20 


14 


DC4 


(CTRL-T) 


0010101 


21 


15 


NAK 


(CTRL-U) 


0010110 


22 


16 


SYN 


(CTRL-V) 


0010111 


23 


17 


ETB 


(CTRL-W) 


0011000 


24 


18 


CAN (CTRL-X) 


0011001 


25 


19 


EM 


(CTRL-Y) 


0011010 


26 


lA 


SUB 


(CTRL-Z) 


0011011 


27 


IB 


ESC 


(CTRL-[) 


0011100 


28 


IC 


FS 


(CTRLA) 


0011101 


29 


ID 


GS 


(CTRL-D 


0011110 


30 


IE 


RS 


(CTRL--) 


0011111 


31 


IF 


US 


(CTRL-_) 


0100000 


32 


20 


(SPACE) 1 


0100001 


33 


21 


! 




0100010 


34 


22 


" 




0100011 


35 


23 


# 




0100100 


36 


24 


$ 




0100101 


37 


25 


% 





- mDIGITAL RESEARCH'" 



CP/M 3 User's Guide 



B ASCII and Hexadecimal Conversions 





Table B-2. 


(continued) 




Binary 


Decimal 


Hexadecimal 


ASCII 


0100110 


38 


26 


6c 


0100111 


39 


27 




0101000 


40 


28 


( 


0101001 


41 


29 


)^ 


0101010 


42 


2A 




0101011 


43 


2B 


+ 


0101100 


44 


2C 


^ 


0101101 


45 


2D 




0101110 


46 


2E 




0101111 


47 


2F 


/ 


0110000 


48 


30 





0110001 


49 


31 


1 


0110010 


SO 


32 


2 


0110011 


51 


33 


3 


0110100 


52 


34 


4 


0110101 


53 


35 


5 


0110110 


54 


36 


6 


0110111 


55 


37 


7 


0111000 


56 


38 


8 


0111001 


57 


39 


9 


0111010 


58 


3A 




onion 


59 


3B 




0111100 


60 


3C 


< 


onnoi 


61 


3D 


= 


0111110 


62 


3E 


> 


0111111 


63 


3F 


> 


1000000 


64 


40 


@ 


1000001 


65 


41 


A 


1000010 


66 


42 


B 


1000011 


67 


43 


C 


1000100 


68 


44 


D 


1000101 


69 


45 


E 


1000110 


70 


46 


F 


1000111 


71 


47 


G 


1001000 


72 


48 


H 


1001001 


73 


49 


I 


1001010 


74 


4A 


J 


1001011 


75 


4B 


K 



IIDIGITAL RESEARCH" - 



B ASCII and Hexadecimal Conversions 



CP/M 3 User's Guide 





Tabu B-2. 


(continued) 




Binary 


Decimal J 


Hexadecimal 


ASCII 


1001100 


76 


4C 


L 


1001101 


77 


4D 


M 


lOOUlO 


78 


4E 


N 


lOOUU 


79 


4F 


O 


1010000 


80 


50 


P 


1010001 


81 


51 


Q 


1010010 


82 


52 


R 


1010011 


83 


53 


S 


1010100 


84 


54 


T 


1010101 


85 


55 


U 


1010110 


86 


56 


V 


1010111 


87 


57 


W 


1011000 


88 


58 


X 


1011001 


89 


59 


Y 


1011010 


90 


5A 


Z 


1011011 


91 


5B 


1 


1011100 


92 


5C 


\ 


1011101 


93 


5D 


1 


1011110 


94 


5E 




1011111 


95 


5F 


< 


1100000 


96 


60 




1100001 


97 


61 


a 


1100010 


98 


62 


b 


1100011 


99 


63 


c 


1100100 


100 


64 


i 


1100101 


101 


65 


e 


1100110 


102 


66 


f 


UOOIU 


103 


67 


e 


1101000 


104 


68 


h 


1101001 


105 


69 


i 


1101010 


106 


6A 


i 


1101011 


107 


6B 


k 


1101100 


108 


6C 


1 


UOUOl 


109 


6D 


m 


1101110 


110 


6E 


n 


1101111 


111 


6F 


o 


1110000 


112 


70 


P 


1110001 


113 


71 


<! 



- m DIGITAL RESEARCH™ 



CP/M 3 User's Guide 



B ASCII and Hexadecimal Conversions 





Tabu B-2. 


(continued) 




Binary | 


Decimal 


Hexadecimal 


ASCU 


IHOOIO 


114 


72 


I 


1110011 


115 


73 


s 


1110100 


116 


74 


t 


1110101 


117 


75 


u 


mono 


118 


76 


V 


1110111 


119 


77 


w 


1111000 


120 


78 


X 


1111001 


121 


79 


y 


1111010 


122 


7A 


z 


1111011 


123 


7B 


{ 


1111100 


124 


7C 




1111101 


125 


7D 


) 


1111110 


126 


7E 




1111111 


127 


7F 


DEL 



End of Appendix B 



IBDIGITAL RESEARCH™ 



Appendix C 
Filetypes 



CP/M 3 identifies every file by a unique file specification, which consists of a drive 
specification, a filename, a filetype, and an optional password. The filetype is an 
optional three- character ending separated from the filename by a period. The filetype 
generally indicates a special kind of file. The following table lists common filetypes 
and their meanings. 



Tabic C-1. Common Filetypes 



Type 


Meaning 


ASM 


Assembly language source file; the CP/M 3 assemblers assemble or 
translate a type ASM file into machine language. 


BAK 


Back-up file created by text editor; the editor renames the source file 
with this filetype to indicate that the original file has been processed. 
The original file stays on disk as the back-up file, so you can refer 
to it. 


BAS 


CBASIC program source file. 


COM 


8080 executable file. 


ERL 


Pascal/MT+"' relocatable file. 


HEX 


Program file in hexadecimal format. 


INT 


CBASIC program intermediate language file. 


IRL 


Indexed REL file produced by LIB. 


LIB 


Used by MAC and RMAC for macro libraries. The ED R command 
reads files of type LIB. The ED X command writes files of type LIB. 
Printable file displayable on console or printer. 



m DIGITAL RESEARCH™ 



CP/M 3 User's Guide — 



Tabic C-1. (condnued) 



Type 


Meaning 


OVL 


Program overlay file. PL/I-80 compiler overlays files; you can create 
overlay files with LINK-80. 


PAS 


Pascal/MT+ source progtam filetypc. 


PLI 


PL/1-80 source program filetype. 


PRL 


Page Relocatable file; a file that does not require an absolute seg- 
ment. It can be relocated in any Page Boundary {256 Bytes). 


PRN 


Printable file displayable on console or printer. 


REL 


Relocatable file produced by RMAC and PI71-80 that can be linked 
by LINK-80. 


SPR 


System Page Relocatable file; system files required to generate 
CP/M 3, such as BNKBDOS.SPR, BDOS.SPR, BIOS.SPR, and 
RESBDOS.SPR. 


SUB 


Filetype required for submit file containing one or mote CP/M 3 
commands. The SUBMIT program executes commands in files of 
type SUB, providing a batch execution mode for CP/M 3. 


SYM 


Symbol table file. MAC, RMAC, and LINK-80 output files of type 
SYM. SID and ZSID read files of type SYM. 


SYS 


System file for CP/M 3. 


TEX 


Source file for TEX-80™, the Digital Research text formatter. 


TOK 


Pascal/MT+ intermediate language file. 


XRF 


Cross-reference file produced by XREF. 


$$J 


Temporary file. 



End of Appendix C 



m DlCrTAL RE.SEARCH™ 



Appendix D 
CP/M 3 Control Character Summary 



Table D-1. Nonbanked CP/M 3 Control Characters 



Meaning 



CTRL-J 



Terminates the executing program and redisplays the system 
prompt, provided the cursor is at the beginning of the command 
Hne. Also, if you halt scrolling with CTRL-S, you can terminate 
the program with a CTRL-C. 

Forces a physical carriage return but does not send the com- 
mand line to CP/M 3. Moves the cursor to the beginning of the 
next hne without erasing your previous input. 

Deletes a character and moves the cursor left one character 

position. 

Moves the cursor to the next tab stop. Tab stops are automati- 
cally set at each eighth column. Has the same effect as pressing 
the TAB key. 

Sends the command line to CP/M 3 and returns the cursor to 
the left of the current line. Has the same effea as a RETURN 
or a CTRL-M. 

Sends the command line to CP/M 3 and returns the cursor to 
the left of the current line. Has the same effect as a RETURN 
or a CTRL-J. 

Echoes all console activity to the printer. The first time you type 
CTRL-P, CP/M 3 rings a bell at your console. You can use 
CTRL-P after you halt scrolling with CTRL-S. A second CTRL- 
P ends printer echo; no bell rings. CTRL-P has no effect if your 
system does not include a printer. 



BDIGITAL RESEARCH'" 



D CP/M 3 Control Char 



CP/M 3 User's Guide 



Table D-1, (contintied) 



Meaning 



Places a # at the current cursor location, moves the cursor to 
the next line, and displays any partial command you typed so 

far. 

Stops screen scrolHng. If a display scrolls by too fast for you to 
read it, type CTRL-S. CTRL-Q restarts screen scrolling. 

Discards all the characters in the command line, places a # at 
the current cursor position, and moves the cursor to the next 
command line. 



Discards all the characters in the 
cursor to the beginning of the 



id line, and moves the 



IS DIGITAL RESEARCH'" 



CP/M 3 User's Guide D CP/M 3 Control Characier Summary 

Table D-2. Banked CP/M 3 Line-editing Control Characters 



Meaning 



CTRL-A 
CTRL-B 



CTRL-F 
CTRL-G 

CTRL-H 
CTRL-I 

CTRL-J 

CTRL-K 
CTRL-M 



Moves the cursor one character co the left. 

Moves the cursor to the beginning of the command line without 
having any effect on the contents of the line. If the cursor is at 
the beginning, CTRL-B moves it to the end of the Hne. 

Terminates the executing program and redisplays the system prompt, 
provided the cursor is at the beginning of the command line. Also, 
if you halt scrolling with CTRL-S, you can terminate the program 
with a CTRL-C. 

Forces a physical carriage return but does not send the command 
line to CP/M 3. Moves the cursor to the beginning of the next 
hne without erasing the previous input. 

Moves the cursor one character to the right. 

Deletes the character indicated by the cursor. The cursor does not 

Deletes a chataaer and moves the cursor left one charaaer position. 

Moves the cursor to the next tab stop. Tab stops are automatically 
set at each eighth column. Has the same effect as pressing the 
TAB key. 



Sends the command line to CP/M 3 and returns the cursor to the 
beginning of a new line. Has the same effect as a RETURN or a 
CTRL-M keystroke. 

Deletes to the end of the line from the cursor. 



Sends the command line to CP/M 3 and returns the cursor to the 
beginning of a new line. Has the same effect as a RETURN or a 
CTRL-J keystroke. 



m DIGITAL RESEARCH'" 



D CP/M 3 Control Character Summary 



CP/M 3 User's Guide 



Table D-2. (continued) 



Meaning 



Echoes all console activity to the printer. The first time you type 
CTRL-P, CP/M 3 rings a bell at your console. You can use CTRL- 
P after you halt scroUing with CTRL-S. A second CTRL-P ends 
printer echo; no bell rings. CTRL-P has no effect if your system 
does not include a printer. 

Retypes the command line. Places a # at the current cursor loca- 
tion, moves the cursor to the next line, and retypes any partial 
command you typed so far. 

Stops screen scrolling. If a display scrolls by too fast for you to 
read it, type CTRL-S. CTRL-Q restarts screen scroHing. 

Discards all the characters in the command line, places a # at the 
current cursor position, and moves the cursor to the next line. 
However, you can use a CTRL-W to recall any charaaers that 
were to the left of the cursor when you pressed CTRL-U. 

Recalls and displays previously entered command line both at the 
operating system level and in executing programs, if the CTRL- 
W is the first character entered after the prompt. CTRL-J, CTRL- 
M, CTRL-U, and RETURN define the command line you can 
recall. If the command line contains charaaers, CTRL-W moves 
the cursor to the end of the command line. If you press RETURN, 
CP/M 3 executes the recalled command. 

Discards all the charaaers left of the cursor and moves the cursor 
to the beginning of the current line. CTRL-X saves any characters 
right of the cursor. 



End of Appendix D 



m DIGITAL RESEARCH™ 



Appendix E 
User's Glossary 



ambiguous filename: Filename that contains either of the CP/M 3 wildcard charac- 
ters, ? or *, in the primary filename or the filetype or both. When you use wildcard 
characters, you create an ambiguous filespec and can easily reference more than one 
CP/M 3 file. See Section 2 of this manual. 

applications program: Program that solves a specific problem. Typical applications 
programs are business accounting packages, word processing [editing) programs, and 
mailing list programs. 

argument: Symbol indicating a place into which you can substitute a number, letter, 
or name to give an appropriate meaning to a command line. 

ASCII: The American Standard Code for Information Interchange is a standard 
code for representation of numbers, letters, and symbols. An ASCII text file is a file 
that can be intelligibly displayed on the video screen or printed on paper. See Appen- 
dix B. 

attribute: File characteristic that can be set to on or off. 

back-up: Copy of a disk or file made for safe keeping, or the creation of the back- 
' up disk or file. 

^ bit: Switch in memory that can be set to on (1) or off (0). Bits are grouped into 

1 I bytes. 

.^ block: Area of disk. 

bootstrap: Process of loading an operating system into memory. Bootstrap proce- 
dures vary from system to system. The boot for an operating system must be custom- 
ized for the memory size and hardware environment that the operating system man- 
ages. Typically, the boot is loaded automatically and executed at power up or when 
the computer is reset. Sometimes called a "cold start." 

buffer: Area of memory that temporarily stores data during the transfer of infor- 
mation. 



RESEARCH"' 



E User's Glossary CP/M 3 User's Guide 

built-in commands: Commands that permanently reside in memory. They respond 
quickly because they are not accessed from a disk. 

byte: Unit of memory or disk storage containing eight bits. 

character string: Any combination of letters, numbers, or special characters on your 
keyboard. 

command: Elements of a CP/M 3 command line. In general, a CP/M 3 command 
has three parts: the command keyword, the command tail, and a carriage return 
keystroke. 

command file: Series of coded machine executable instructions stored on disk as a 
program file, invoked in CP/M 3 by typing the command keyword next to the system 
prompt on the console. CP/M 3 command files generally have a filetype of COM. 
Files are either command files or data files. Same as a command program. 

command keyword: Name that identifies an CP/M 3 command, usually the primary 
filename of a file of type COM, or a built-in command. The command keyword 
precedes the command tail and the carriage return in the command line. 

command syntax: Statement that defines the correct way to enter a command. The 
correct structure generally includes the command keyword, the command tail, and a 
carriage return. A syntax line usually contains symbols that you should replace with 
actual values when you enter the command. 

command tail: Part of a command that follows the command keyword in the com- 
mand line. The command tail can include a drive specification, a filename and/or 
filetype, and options or parameters, but cannot exceed 128 characters. Some com- 
mands do not require a command tail. 

concatenate: Term that describes one of PIP's operations that combines two or 
more separate files into one new file in the specified sequence. 

console: Primary input/output device. The console consists of a listing device such 
as a screen and a keyboard through which the user communicates with the operating 

system or applications program. 



- m DIGITAL RESEARCH" 



CP/M 3 User's Guide E User's Glossary 

control character: Nonprinting character combination that sends a simple com- 
mand to CP/M 3. Some control characters perform line editing functions. To enter a 
control character, hold down the CTRL key on your terminal and strike the charac- 
ter key specified. See Appendix D. 

cursor: One-character symbol that can appear anywhere on the console screen. The 
cursor indicates the position where the next keystroke at the console will have an 
effect. 

data file: Nonexecutable collection of similar information chat generally requires a 
command file to manipulate it. 

default: Currently seleaed disk drive and/or user number. Any command that does 
not specify a disk drive or a user number references the default disk drive and user 
number. When CP/M 3 is first invoked, the default disk drive is drive A, and the 
default user number is 0, until changed with the USER command. 

delimiter: Special characters that separate different items in a command line. For 
example, in CP/M 3, a colon separates the drive spec from the filename. A period 
separates the filename from the filetype. Brackets separate any options from their 
command or filespcc. Commas separate one item in an option list from another. All 
of the preceding special characters are delimiters. 

directory: Portion of a disk that contains descriptions of each file on the disk. In 
response to the DIR command, CP/M 3 displays the filenames stored in the directory. 

DIR attribute: File attribute. A file with the DIR attribute can be displayed by a 
DIR command. The file can be accessed from the default user number only. 

disk, diskette: Magnetic media used to store information. Programs and data are 
recorded on the disk in the same way that music is recorded on a cassette cape. The 
term diskette refers to smaller capacity removable floppy diskettes. Disk can refer to 
a diskette, a removable cartridge disk, or a fixed hard disk. 



disk drive: Peripheral device that reads and writes on hard or floppy disks. CP/M 3 
assigns a letter to each drive under its control. For example, CP/M 3 can refer to the 
drives in a four-drive system as A, B, C, and D. 



PDIGITAL RESEARCH ' 



E User's Glossary CP/M 3 User's Giude 

editor: Utility program that creates and modifies text files. An editor can be used 
for creation of documents or creation of code for computer programs. The CP/M 3 
editor is invoked by typing the command ED next to the system prompt on the 
console. (See ED in Section 6 of this manual). 

executable: Ready to be run by the computer. Executable code is a series of instruc- 
tions that can be carried out by the computer. For example, the computer cannot 
execute names and addresses, but it can execute a program that prints ail those 
names and addresses on mailing labels. 

execute a program: Start a program executing. When a program is running, the 
computer is executing a sequence of instructions. 

FCB: See File Control Block. 

file: Collection of characters, instructions or data stored on a disk. The user can 
create files on a disk. 

File Control Block: Structure used for accessing files on disk. Contains the drive, 
filename, filetype and other information describing a file to be accessed or created on 
the disk. 

filename: Name assigned to a file. A filename can include a primary filename of 1-8 
characters and a filetype of 0-3 characters. A period separates the primary filename 
from the filetype. 

file spedficadon: Unique file identifier. A complete CP/M 3 file specification includes 
a disk drive specification followed by a colon (d:), a primary filename of 1 to 8 
characters, a period, and a filetype of to 3 characters. For example, b:example.tex 
is a complete CP/M 3 file specification. 

filetype: Extension to a filename. A filetype can be from to 3 characters and must 
be separated from the primary filename by a period. A filetype can tell something 
about the file. Certain programs require that files to be processed have certain file- 
types {see Appendix C), 

floppy disk: Flexible magnetic disk used to store information. Floppy disks come in 
5 1/4- and 8-inch dia 



hard disk: Rigid, platter like, magnetic disk sealed i 
stores more information than a floppy disk, 



nCP/M 3 User's Guide E User's Glossary 

hardware: Physical components of a computer. 
{ I hex iilc: ASCII -printable representation of a command (machine language) file. 

n hexadecimal notation: Notation for the base 16 number system using the symbols 
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, and F to. represent the sixteen digits. 
Machine code is often converted to hexadecimal notation because it can be easily 
represented by ASCII characters and therefore printed on the console screen or on 
n paper (see Appendix B). 

input: Data going into the system, usually from an operator typing at the terminal 
^ or by a program reading from the disk. 

interface: Object that allows two independent systems to communicate with each 
other, as an interface between hardware and software in a microcomputer. 

n 

' I/O: Abbreviation for input/output. 

!^ keyword: See command keyword, 

kilobyte: 1024 bytes denoted as IK. 32 kilobytes equal 32K. 1024 kilobytes equal 
(■• one megabyte, or over one million bytes. 

list device: Device such as a printer onto which data can be listed or printed. 

J I logical: Representation of something that might or might not be the same in its 
I actual physical form. For example, a hard disk can occupy one physical drive, and 
yet you can divide the available storage on it to appear to the user as if it were in 
•^ several different drives. These apparent drives are the logical drives. 

megabyte: Over one million bytes; 1024 kilobytes. See byte and kilobyte. 

I j microprocessor: Silicon chip that is the Central Processing Unit (CPU) of [he micro- 
computer. 

n operating system: Collection of programs that supervises the running of other pro- 
grams and the management of computer resources. An operating system provides an 
orderly input/output environment between the computer and its peripheral devices. 

I option: One of many parameters that can be part of a command tail. Use options 

to specifiy additional conditions for a command's 

I m DltiltAI. REStARCH'" 



E User's Glossary CP/M 3 User's Guide 

output: Data that the system sends to the console or disk. 

parameter: Value in the command tail that provides additional information for the 
command. Technically, a parameter is a required element of a command. 

peripheral devices: Devices external to the CPU. For example, terminals, printers, 
and disk drives are common peripheral devices that are not part of the processor, 
but are used in conjunction with it. 

physical: Actual hardware of a computer. The physical environment varies from 
computer to computer. 

primary filename: First 8 characters of a filename. The primary filename is a unique 
name that helps the user identify the file contents. A primary filename contains 1 to 
8 characters and can include any letter or number and some special charaaers. The 
primary filename follows the optional drive specification and precedes the optional 
filetype. 

program: Series of specially coded instructions that performs specific tasks when 
executed by a computer. 

prompt: Characters displayed on the screen to help the user decide what the next 
appropriate aaion is. A system prompt is a special prompt displayed by the operating 
system. The system prompt indicates to the user that the operating system is ready 
to accept input. The CP/M 3 system prompt is an alphabetic charaaer followed by 
an angle bracket. The alphabetic character indicates the default drive. Some applica- 
tions programs have their own special system prompts. 

Read-Only: Attribute that can be assigned to a disk file or a disk drive. When 
assigned to a file, the Read-Only attribute allows you to read from that file but not 
change it. When assigned to a drive, the Read-Only attribute allows you to read any 
file on the disk, but prevents you from adding a new file, erasing or changing a file, 
renaming a file, or writing on the disk. The SET command can set a file or a drive to 
Read-Only. Every file and drive is either Read-Only or Read-Write. The default 
setting for drives and files is Read- Write, but an error in resetting the disk or chang- 
ing media automatically sets the drive to Read-Only until the error is corrected, files 
and disk drives can be set to either Read-Only or Read-Write. 



- m DIGITAL RESEARCH'" 



CP/M 3 User's Guide E User's Glossary 

Read- Write: Attribute that can be assigned to a disk file or a disk drive. The Read- 
Write attribute allows you to read from and write to a specific Read-Write file or to 
any file on a disk that is in a drive set to Read-Write. A file or drive can be set to 
cither Read-Only or Read-Write, 

record: Collection of data. A file consists of one or more records stored on disk. 
An CP/M 3 record is 128 bytes long. 

RO: See Read-Only. 

RW: See Read-Write. 

sector: Portion of a disk track. There are a specified number of sectors on each 
track. 

software: Specially coded programs that transmit machine- readable instructions to 
the computer, as opposed to hardware, which is the actual physical components of a 
computer, 

source file: ASCII text file that is an input file for a processing program, such as an 
editor, text formatter, or assembler. 

string: See character string 

syntax: Format for entering a given command. 

system attribute: File attribute. You can give a file the system attribute by using the 
SYS option in the SET command. A file with the SYS attribute is not displayed in 
response to a DIR command; you must use DIRS (see Section 5). If you give a file 
with user number the SYS attribute, you can read and execute that file from any 
user number on the same drive. Use this feature to make your commonly used 
programs available under any user number. 

system prompt: Symbol displayed by the operating system indicating that the sys- 
tem is ready to receive input. See prompt. 

terminal: See console. 

track: Concentric rings dividing a disk. There are 77 tracks on a typical eight -inch 
floppy disk. 



m DIGITAL RESEARCH™ - 



E User's Glossary CP/M 3 User's Guide 

turn-key application: Application designed for the noncomputer-oriented user. For 
example, a typical turn-key application is designed so that the operator needs only to 
turn on the computer, insert the proper program disk, and select the desired proce- 
dure from a selection of functions (menu) displayed on the screen. 

upward-compatible: Term meaning that a program created for the previously released 
operating system (or compiler, etc.) runs under the newly released version of the 
same operating system. 

user number: Number from to 15 assigned to a file when it is created. User 
numbers can organize files into sixteen file groups. 

utility: Tool. Program that enables the user to perform certain operations, such as 
copying files, erasing files, and editing files. Utilities are created for the convenience 
of programmers and users. 

wildcard characters: Special characters that give CF/M 3 a pattern to match when 
it searches the directory for a file. CP/M 3 recognizes two wildcard characters, ? and 
*. The ? can be substituted for any single character in a filespec, and the * can be 
substituted for the primary filename or the tiletype or both. By placing wildcard 
characters in a filespec, you create an ambiguous filespec and can quickly reference 
one or more files. 



End of Appendix E 



- IS DIGITAL RESEARCH™ 



Indec 



#, 3-3 


5-104, 5-107, 6-6 


5 in SUB file, 5-110 


55S, filetype, 5-4 


Scd option (LINK'- ), 5-57 


Sid option (LINK), 5-57 


5Ld option (LINK), 5-57 


5Gd option (LINK), 5-57 


5P option (XREF'^ ), 5-117 


SSd option (LINK), 5-57 


< precedes input, 5-110 


<cr>, 5-6 


?, 5-6 


(), 5-6 


*, 5-6 


as default drive, 5-96 


[]. 5-6 


", 5-6 


as operator, 5-104 


f ] , 5-6 


1, 5-6 


*ft command (ED), 5-31 


*M opt 


on (MAC- ), 5-60 


+ 1 opt 


on (MAC), 5-60 


+L Opt 


on (MAC), 5-60 


■t-Q opt 


on (MAC), 5-60 


+ S opt 


on (MAC), 5-60 


-1 opt 


on (MAC), 5-60 


-L opt 


on (MAC), 5-60 


-M option (MAC), 5-60 


-nL command (ED), 5-32 


-nP coimnand (ED), 5-33 


-nT cominand (ED), 5-34 


-Q option (MAC), 5-60 


-S option (MAC), 5-60 


-U cominand (ED), 5-34 


-V command (ED), 5-34 


12S-byt 


e records, 5-23 



A command (ED), 5-30, 5-31 

LINK, 5-56 

Input /Output, 5-60 

PIP, 5-73 
access mode, 5-100 
ACCESS option (SET), 2-8 



lachii 



al, 5-5; 
code, 



5-59 



ALL op t ii 

DRIVES (DIR), 5-22 
USERS (DIH), 5-25 
alter CPU state, 5-106 
alternative items, 5-6 
ambiguous filespec, 2-5 
Append cominand (ED), 5-3: 
ARCHIVE option (PIP), 5-' 
ARCHIVE=OFF (SET), 5-87 
ARCHIVE=ON (SET), 5-87 
arguments, 5-110 
ASCII, 5-29 



cha; 
file, 4-2 






form 



5-29 



ASM, 5-1, 

filetype, 5-4 
source drive, 5-60 
Assemble command (SID'" 
assembly language progr. 



iign 
label pass 






il de' 



ak prompt 

ED, 5-30 

PIP, 1-7, 5-70 
ATT option (DIR) 
attach 

header record, 5-42 

RSX files, 5-40 



5-90 

5-14, 5-16 



5-22 



paging, 3-1 

submit, 4-7 

AUX:, 5-14, 5-1 

ary 



8, 5-69 
5-69 






input 

logic. 

output device, 5-69 
AUXILIARY:, 5-14 
AUXIN: , 3-9, 5-14 
AUXOUT: , 3-9, 5-14 



B command (ED), 5-31 




B option (LINK), 6-56 




back-up disks, 1-5, 5-9, 


, 5-63 


BACKSPACE key, 3-2 




backtrace, 5-103 




BAK file, 5-35 




banked CP/M 3 line-edit: 


Ing 


control characters, 




3-5, D-3 




BAS filetype, 5-4 




batch conunanda, 5-109 




baud rate, 4-3, 5-17 




BDOS, A-1 




BIOS link, 5-56 




booting the system, 1-1 




braces, 5-6 




breakpoint, 5-105 




built-in commands, 1-3, 


4-1 


abbreviations, 4-2 





C command (ED), 5-31 
C option (PIP), 5-72 
Call command (SID), 5-105 
CCP, 5-105 

filename, 5-31 



disks 



2-9 



controlling output, 3-1 

input device, 5-69 

input from file, 5-44 

message destination, 5-57 

output, 5-59 

output device, 5-69 

page, 5-98 
CONSOLEt, 5-14 
context editor, 5-30 
control characters, 1-2 

banked CP/M 3, 3-5, D-3 

nonbanked CP/M 3, 3-3, D-1 

in SUB file, 5-112 
copy, 1-5 

disks, 1-5 

files, 5-63 

memory, 5-85 
5-9 



. A-1 



to /from dev 
COPYSYS comma 
1-6, 4-3, 
CP (character 
CP/M 3 messag 
CPM3 .SYS, 5-9 
CR. 1-2 
CREATE 

COM file, 5-40 
file, 5-30, 5-63 
option (HELP), 5-49 
option (SET), ~ " 



63 



efer. 



lary, 



5-117 



5-4, 5-84, 5-96 
I file, 5-41 
I files, 5-63. 5-67 



file. 


5-51 




form 1 


cules 


1, 5-5 


keyword, 1 


-2, 5-4 




1-2, 


4-5 




ry, 5 


i-I 


tail. 


1-2 








utility, 4- 


comment 


deli 


miter, 5-3 




::atic 


ins protocol 


CON:, 5 


-14, 


5-68, 5-69 


concatei 


natic 


)n, 5-67 


CONFIRM 


opt i 


on (ERASE), 


COfJIN: , 


3-9, 


5-14 


CO SOU T: 


- 3-g 


1, 5-14 



CTBL-C, 2-10, 5-68, 5-114 
CTRL-P, 3-1 , 5-115 
CTRL-Q, 3-1, 5-114 
CTRL-S, 3-1, 5-114 
CTRb-Z, 5-36, 5-67, 5-68, 
5-69, 5-71 



D command 

ED, 5-31 

SID, 5-105 
D option 

LIB~ , 5-54 

LINK, 5-56 

PIP, 5-72 
data 

files, 2-1 

origin option (LINK), 5-56 
DATE command, 4-3, 5-11 

option (DIB), 2-8, 5-22 

stamping, 2-B, 5-52 
DDT- , 5-1 
debug, 5-59 

program, 5-103 
decimal values (SID), 5-105 
default 

drive, 1-1, 1-5, 2-4 



drive attribute, 5-88 




label name, 5-88 




paged output display. 


5-23 


password, 2-9, 5-91 




system page mode, 5-98 




user number, 5-67 




define 




disk search order, 5-96 


filetype search order. 


5-96 


temporary drive, 5-95 




delete 




characters, 3-2, 5-31, 


5-72 


command (ED), 5-31 




file, 5-34, 5-81 




mode, 5-91 




modifier, 5-54 




delimiters, 5-3 




dest-f ilespec, 5-4, 5-8, 


5-64 


assignments, 5-15 




characteristics, 5-15 




device command, 4-3, 5 


-14 


CON, 5-16 




CONSOLE, 5-14 




CUT, 5-16 




driver protocol, 4-3 




names, 5-15, 5-69 




physical-dev option, 5- 


18 



auxiliary input/output, 5-69 
auxiliary logical input, 5-17 
input/output, 3-9 
physical, 5-14 



!-7, 4-2, 5-19, 5-88, 

■101 

■ibute, 5-19, 5-22 

land, 1-3, 5-19 

display options, 5-22, 5-2 

5-24, 5-25 
[FULL], 5-25 

Options, 5-19, 5-21, 5-22 
[SIZE], 5-26 
syntax notation, 5-5 
Lrectory, 2-1 , 2-9, 5-19 
displaying, 5-19, 



sing entr 



5-101 



5-100 



label, 

space, 2-9 
DIRS, 4-2, 5-19 
DIRSYS, 2-7, 4-2, 5-19 
disable password 

protection, 5-90 
disk 

back-up, 1-5, 5-9, 5-63 

changing, 2-9 

destination, 5-10 

drive search order, 5-96 

formatting, 1-5 

label, 5-86, 5-99 

)rd protected, 5-86 






1-5 



space available, 5-99 
display, 5-97, 5-99 
access mode, 5-99 
command (SID), 5-105 
console size, 5-18 
CPU registers, 5-103 
date, 5-11 
directory, 5-19 
directory with options, 5-21 
disk label, 5-99 
disk drive search order, 5-96 
disk space available, 5-99 
drive characteristics, 5-102 
file contents, 5-29, 5-114 
f i lenames, 5-19 
logical device, 5-14 
memory, 5-103, 5-105 
mode (SETDEF ) , 5-97 
patch, 5-62 
phys 



search defij 
symbols, 5- 



5-14, 5-18 
litions, 5-95 



Dn (delete characters} option 

(PIP), 5-72 
drive, 2-3, 2-9, 5-102 

A, 1-1 

attribute, 2-10, 5-88 

characteristics, 5-102 

default, 1-1, 1-5, 2-4 

delimiter, 5-3 

names, 5-59 

protection, 2-10 

search chain, 4-4 

specifier, 2-2, 2-4, 5-1 
DRIVE options (DIR), 5-22 
DUMP 

command, 4-3, 5-29 

option (LIB), 5-54 



E (echo transfer) option 

GET, 5-45 

PIP, 5-66, 5-72 

PUT, 5-78 
E command 

ED, 5-30, 5-31 

SID, 5-105 

option, 5-72 
E* command, 5-105 
ED command, 5-30, 5-93 

affect on time stan^JS, 5-93 

character pointer 
(CP), 5-30 

diskette file error 
messages, 6-31 

error symbols, 6-30 

summary, 5-31 
ellipses, 5-6 
enable 

line numbering command, 5-34 

password protection, 5-99 
end-of-file, 5-69 
EOF: source device, 5-69 
ERA (ERASE) command, 4-2, 5-38 
error messages, A-1 
Escape, 5-32 

examine CPU state (SID), 5-106 
exclamation point, 4-7 
EXCLUDE option (DIR), 5-23 
expand tabs (PIP), 5-74 
extended find string 

command (ED), 5-33 
EXTRACT option (HELP), 
5-48, 5-49 



F command 

ED, 5-31 

SID, 5-105 
F (filter form-feeds) opt 

(PIP), 5-72 
Fl attribute, 5-22 
Fl=ONlOFP (SET), 5-87 
F2 attribute, 5-22 
F2=ONlOFF (SET), 5-97 
F3 attribute, 5-22 
F3=ON I OFF (SET ) , 5-87 
F4 attribute, 5-22 
F4=ONiOFF (SET), 5-87 
FF (form feed) option 

(DIR), 5-23 
file, 2-1 

ling, 2-i 



atego 



2-2 



5-67 



copy, 5-63 
creating, 2-1 
deleting, 5-34, 5-81 
displays, 5-19 
maintenance, 2-1 
naming, 2-2 
program, 2-1 

search, 4-4, 5-57 
size, 5-23 
space, 5-23 
specification, 2-2, 2-3, 

5-1, 5-3 
temporary, 5-64, 5-95 
file attributes, 2-7, 5-19, 
DIR, 2-7, 5-19 
PIP, 5-63, 5-65 
Read-Cnly, 2-8 
Read-Write, 2-8 
SYS, 2-7, 5-19 
filename, 2-2, 5-1 
changing, 5-81 
listing, 5-X9 
file spec, 2-5, 5-2 
filetype, 2-2, 5-1, 5-4, C-1 
delimiter, 5-3 
search order, 5-96 
fill functions, 5-103 
filter form-feeds, 5-72 
FILTER option (PUT), 5-78 
find character string (ED), 

5-31 
finish address (SID), 5-105 



forn-feed, 5-23 



G (Go) command (SID), 5-105 
G (Gn) option 

LINK, 5-56 

PIP, 5-64, 5-67, 5-72 
GENCOM comnand, 5-40 
generate RSX files, 5-41 
GET command 

console input from a 

file, 3-6, 3-7, 4-3, 5-4- 

options, 5-45 
global option delimiters, 5-. 
group commands, 5-109 



H command 

ED, 5-32 

SID, 5-105 
H option, 

MAC, 5-60 

PIP, 5-73 
hard disk, 2-4 
header record, 5-42 
HELP command, 4-9, 5-47 

optiona, 5-47, 5-48 
HELP.COM, 5-49 
HELP .DAT, 5-49 
HELP.HLP, 5-49 



HEX : 



Lie 



debugging, 5-59 
destination driva, 

5-60, 5-34 
generation, 5-51 
transfer, 5-73 
hexadecimal output, 1 

zeroes, 5-69 
HEXCOM command, 
HH (DATE), 5-i; 
HIST utility (SID), 
histogram, 5-108 
HLP filetype, 5-4 



4-3, 5-51 



I command 

ED, 5-32, 5-35 

SID, 5-105 
I option 

LIB, 5-54 

PIP, 5-73 
Ignore option (PIP), 5-73 
imaginary character 

pointer, 5-30 
INDEX option (LIB), 5-54 
INITDIR command, 5-52, 5-92 



nitial 
date and tii 
drive, 1-1 



5-11 






5-32, 



.sk dii 
4-3, 5-52 

CCP command line, 5-10 5 

command (SID), 5-105 

devices, 3-9 
insert 

mode (ED), 5-30 

mode command (ED) 
5-35, 6-14 

string command (ED), 5-32 
install patch number, 5-62 
Intermediate files, 5-57 
IRL filetype, 5-53 



J (juxtapose) 



K (kill) command (ED), 
keyboard, 5-14, 5-69 
kilobyte, 5-99 



L Option (PIP), 5-73 
label, 5-88, 5-99 
created, 5-100 
disk, 5-86, 5-89 
updated, 5-100 
least significant digi 

LENGTH option (DIR), 5- 

levels (HELP), 5-50 



LIB (libcary) command, 
5-53, 5-60 

file, 5-53 

file Bourca, 5-57 

modifiers, 5-54 
line editing, 3-2 

banked CP/M 3, 3-5, 3-6, D-3 

characters (ED), 5-30 

control characters, 3-3, 3-5 

nonbanXed CP/M 3, 3-2, D-1 
line number (ni) command, 

6-11, 6-20 
line nuBtoars, 5-70, 5-73 
lina-faad, 5-69 
lines, 5-14, 5-lS 
LINK command, 4-3, 5-56 

options, 5-56 
LINK-80, 5-53 
LIST (HELP), 5-47 
list 

at printer, 5-115 

f ilanamea, 5-19 

input lines (MAC), 5-60 

instructions (SID), 5-105 

macro lines option 
(MAC), 5-60 

option (HELP), 5-47 

output logical device, 5-17 
literal hex valuaa, 5-104 

addraee, 5-56 

CP/M 3,1-1 

program (SID), 5-105 

symbol table (SID), 5-105 
LOADER option ( GENCCW) , 5-40 
LOCAL symbols, 5-60 
logged in, 1-1 
logical devicas, 3-9, 5-14, 

5-16, 5-63, 5-69 
lowercaaa option (PIP), 5-73 
LPT, 5-18 
LST:, 3-9, 5-14, 5-68, 5-69 



H command 

ED, 5-32 

SID, 5-106 
M option 

LIB, 5-54 

LINK, 5-56 

MAC, 5-60 
MAC command, 4-3, 5-59, 5-117 

input/output options, 5-60 

output file modifiers, 5-60 



assembler, 5-59 

expansion, 5-60 

library source drive, 5-60 

lines, 5-60 
main topic (HELP), 5-49 
memory 

adding, 5-56 

buffer, 6-6 

copying, 5-85 

display (SID), 5-103, 5-105 

size option (LINK), 5-56 
MESSAGE option (DIR), 5-24 
MM (DATE), 5-12 
mnemonic instructions, 5-10 5 
MODULE option (LIB), 5-54 
monitor 

execution, 5-106 

program, 5-103 
most significant digit, 5-104 

character pointer (ED), 5-31 

command (SID), 5-106 

line command, 5-32 

memory block (SID), 5-106 
MS2E, 5-106, 5-107 
multiple 

commands, 4-1, 4-7, 5-70 

file copy, 5-66 



n, 5-5 

N command (ED), 5-33 

N option (PIP), 5-73 

name disk, 5-83 

NAME option, 5-88 

NAMES, 5-15 

NIXT, 5-107 

SL option (LINK), 5-56 

NO 

DISPLAY option (SETDEF), 
5-95, 5-97 

ECHO option (GET), 5-44, 5-45 

FILTER Option (PUT), 5-78 

listing (LINK), 5-56 

output, 5-59 

PAGE (DIR), 5-24 

PAGE (HELP), 5-47 

PAGE (SETDEP), 5-95, 5-98 

PAGE (TYPE), 5-115 
NOECHO option (PUT), 5-79 
nonbanked CP/M 3 

control characters, 3-3, D-1 
NONE mode, 5-91 



nonsyatem files, 5-20 
NOSORT option ( DIR) , 5-24 

.on (DEVICE), 5-17 

(LINK), 5-57 



NOXON opt 

NR option ,__ , 

HULi, 5-68, 5-69 
NULL opt 
5-16 



- (DEVICE), 
5-40 



of files, 5-99 
of free directory 

entriea, 5-99 
syntax notation, S-5 



o, 5-5 

O command (ED), 5-33 
O option (PIP), 5-73 

file destination, 5-57 

file transfer, 5-73 

modules, 5-53 
OC option (LINK), 5-57 
online disk, 2-9 
OP option (LINK), 5-57 
operating system loader, 
option, 5-5, 5-6 

dQlimiters, 5-3 

list, 5-5, 5-22 

items, 5-6 



c bat 



5-6 



OR option (LINK), 5-57 

ORDER, 5-96 

OS option (LINK), 5-57 

Output 

COM file, 5-57 






3-1 



devices, 3-9 
printer, 3-1 
PRL file, 5-57 
RSP file, 5-57 
SPR file, 5-57 
jverwr ite B«ad-Only, 



P command 
ED, 5-33 
SID, 5-106 

P option 
LIB, 5-54 
LINK, 5-57 
MAC, 5-60 
PIP, 5-73 
RMAC- , 5-8. 



page 

display command, 5-: 
eject, 5-69, 5-73 
length, 5-73 
PAGE option 
DEVICE, 5-18 
SETDEF, 5-95, 5-98 
TYPE, 5-114 



paiTi 



5-109 



5-106 
89 



5-6 
parity bit, 5-75 
partial command, 3-3 
pass 1 listing, 5-60 
pass breakpoin 

ass igning to label. 

assigning to file, 5-90 

in file spec ification, 
2-2, 2-3 

in PIP, 5-63 

purpose, 2-8, 5-1 
PassMord-protec tion mode 

disabling /enabling, 5-89 

in DIR, 5-23 

showing, 5-100 

types, 5-91 
PATCH command, 5-62 
PC, 5-106, 5-107 
per ipherai device, 5-14 
physical device, 3-9, 
PIP command, 1-5, 2-1, 
5-8, 5-63 

file concatenation, 5-67 

long form, 5-65 

messages, 5-66 

options, 5-65, 5-71, 5-72 
5-65 



4-3, 



>und 



■ igr 



5-107 



3-1 



77 



printer echo, 
printer output, 

to file, " "' 
PRINTER: , 5-14 
PRN, 5-59 

destination drive, 5-60 

file, 5-59, 5-117 

file drive, 5-84 
PRN:, 5-68, 5-69 
PROFILE. SUB start-up file. 



load ing search 

definitions, 5-96 

origin, 5-57 
PUBLICS option (LIB), 5-54 
PUT command, 3-6, 4-4, 5-79 

console output to file, 5-79 

options, 5-78 

printer output to file, 5-79 



Q command (ED), 5-33 
Q option, 

LINK, 5-57 

PIP, 5-74 
quit copy (PIP), 5-74 



R command 

ED, 5-33 

SID, 5-106 
B option 

PIP, 5-74 

RMAC, 5-84 
range of options, 5-6 

code/symbola (SID), 5-106 

mode, 5-91 

system flies, 5-74 
Read-only, 2-8 

attribute, 2-8, 5-86 

files, 5-65 

option (Dm), 5-24 

syntax notat ion, 5-5 
Read-Write, 2-8 

attribute, 2-8, 5-86 

option (DIR), 5-24 

syntax notation, 5-5 
real-tiBie breakpoints, 5-103 
recovering from editing 

errors, 6-30 
redirect console/printer 

input/output, 3-1, 3-6 
register pair, 5-105 
REL (relocatable) program, 4-3 

file drive destination, 5-84 

format, 5-53 

modules, 4-4 
relocatable macro aaaembler 

See BHAC 
REN (SEHflME) command, 
4-2, 5-81 

file, 5-63 

messages, 5-81, 5-82 



repeated execution of editing 
coBunands, 6-24 

modifier, 5-54 

online disk, 2-9 

RSX files, 5-42 
reserved characters, 5-3 
RESET/RESTART button, 1-1 
res ident sys tem 

extensions, 5-40 

process, 5-57 
restore COM file, 5-41 
RETURN key, 1-2 

equivalent characters, 5-71 
RMAC command, 4-3, 4-4, 
5-84, 5-117 

options, 5-84 
RO 

See Read-Cnly 
RSX files 

add, 5-42 

attach, 5-40 
RH 

See Itead-Hrite 



S command 

ED, 5-33 

SID, 5-106 
S option 

LINK, 5-57, 5-58 

PIP, 5-74 

RMAC, 5-84 
a string. 5-5 
SAVE command, 5-31, 5-85 
save memory, 5-85 
SCB option, 5-40 
screen size, 5-14, 5-18 
scroll, 5-24 

disk drives, 5-96 
file, 4-4, 5-57 
filetypea, 5-96 
order procedure for 
a program file, 4-5 
select modifier, 5-54 



m protocol, 5-14 

5-18 
number, 5-116 



date, 5-11 
physical de' 
attribute 



file attributes, 5-86 
memory values, 5-106 
password protec tion, 5-89 
5-14, 5-18 



5-11 
5-92 
5-92 

5-92 



time, 5-11 

time of day, 

time atanps, 

[ACCESS =ON], 

[CREATE=ON], 

[DEFAULT=pas sword] , 5-91 

[PR0TECT=OFF], 5-89 

[PROTECT=ON], 5-89 

[UPDATE=ON], 5-92 

{d:! [BO], 5-88 

[d:l [RW], 5-88 
SETDEF command, 4-4, 4-6, 5-95 

drive tenporary files, 5-95 

search definitions, 5-95 

search order, 5-96 

system display mode, 5-97 

system page mode, 5-98 

[TSMPOBARY=D;] , 5-95 
SHOW command, 2-9, 4-4, 
5-90, 5-99 

access mode, 5-99 

[d:i [DIR], 5-101 

id:} [DRIVE], 5-102 

[di 1 [LABEL], 5-99 

Id:} [USERS], 5-100 

directory entries, 5-101 

disk space, 5-99 

drive characteristics, 5-102 

user number, 5-100 

password protection, 5-90 
SID command, 4-4, 5-103, 
5-105, 5-106 

pronpt, 5-107 

utilities, 5-107 
single file cc^y, 5-63 

format, 5-26 

of screen, 5-14, 5-18 

option (DIR), 5-24 



SPACE, 5-99 

available, 5-52 
characters, 5-3, 5-5 
special header, 5-40 



square bradcets, 5-6, 

5-65, 5-71 
src-filespec, 5-4, 5-64 
SS (DATE), 5-12 
stack pointer, 5-104 
stan^ update, 5-100 



address, 5-106 




console/printer output, 3-1 


copy, 5-74 




starting CP/M 3, 1-1 




STAT, 5-1 




stop console/printer 




ou tpu t , 3-1 




storage space, 2-9 




SUB, 5-96 




file, 5-111 




file type, 5-4 




SUBMIT command, 4-4, 5 


-109 


program input lines, 


5-110 


start-up file, 5-113 




subroutines, 5-106 




substitute string 




command, 5-33 




subtopic, 5-47, 5-49 




aupertopic, 5-49 




SYM, 5-59 




destination drive, 5' 


-60 


file, 5-59, 5-117 




file drive, 5-84 




symbol 




file destination, 5- 


57 


table, 5-56, 5-58 




table file, 5-57, 5-. 


L05 


symbolic 




disassembly, 5-103 




expression, 5-103, 5 


-104 


operators, 5-104 




Symbolic Instruction 




Debugger, 5-103 




symbols with question 




mark, 5-57 




syntax notation, 5-4, 


5-7 


SYS, 2-7 




file attribute, 2-7, 




5-19, 5-86 




option (DIR), 5-24 




syntax notation, 5-6 




SYSTEM option 




GET, 5-44 




PUT, 5-77, 5-78 





ays tern 

console output, 5-17 
Control Block, 5-40 
copying, 5-9, 5-67 
disk, 1-1, 5-10 
file CPM3.SYS, 5-9 
messages, A-1 
options, 4-4, 
page mode, 5-98 
page relocatable, 5-5 
pronpt, i-1, 1-5, 2-9 
RESET , 1-1 
tracks, 5-9 



transient utility commands, 
1-3, 4-1, 4-3 

rate, 5-17 

speed, 5-18 
turn on /off 

systan display node, 5-97 

system page mode, 5-98 
TYP, 4-2, 5-2 
TYPE command, 4-2, 5-34, 5-114 

messages, 5-114 

u 



T command 

ED, 5-34 

SID, 5-106 
T option (PIP), 5-74 
tab 

characters, 5-114 

expansion, 5-69, 5-74 

key, 3-3 

stop, 3-3 
TEMPORARY option (SETDEP), 



console outpu 
file, 5-46 



utput to file, 

4-9 
m, 5-103 



editor (ED), 2-1 
time staa^JS, 5-52, 5-86, ! 

access, 5-92 

create, 5-92 

date atanpB, 2-7, 2-8 

time file modified, 5-9: 

update, 5-92 
time-specification 

format, 5-12 
top-of-stack item, 5-104 

format, 5-49 
levels, 5-50 
topic name, 5-49 

program execution, S-lOt 
without call, 5-106 

TRACE, UTL, 5-107 

traceback, 5-103 



ED, 5-34 

SID, 5-106 

U option, 5-74 

operator, 5-104 
update 

RSX files, 5-42 

time stamp, 5-100 
uppercase, 1-2, 5-36, 5-75 

command, 5-34 
USE, 4-2 
USER command, 4-2, 5-67, 5-116 

memory, 5-30 

number, 2-4, 2-7, 5-67, 
5-72, 5-99 

number information, 5-100 

number range, 5-116 

option (DIR), 5-25 

u s er -de finable file 

attributes, 5-22 



5-15, 5-16 



ED, 5-30, 5-34 

SID, 5-106 
W option 

PIP, 5-65, 5-75 
wait command, 5-34 
warm start, 4-8 



ildcard, 5-3, 5-6, 5-82 

characters, 2-5 

filespec, 5-4, 5-38, 5-66 

patterns, 2-7 

specifications, 2-6 
■rite 

command (ED), 5-34 

memory to file (SID), 5-101 

mode, 5-91 

over files, 5-76 

over RO, 5-76 
rite-protected, 2-8 



X command 

ED, 5-34 

SID, 5-106 
X output option (BMAC), 5- 
XON, 5-17 

XON/XOFF protocol, 5-17 
XREF command, 4-4, 5-117 
XRF file, 5-117 



YY (DATE), 5-12 



NOTES 



NOTES 



NOTES 



DIGITAL 
RESEARCH' 



CP/M Plus™ 

Operating System 

Command Summary 



COPYRIGHT 

Copyright © 1984 Digital Research Inc. All eights 
reserved. No part of this publication may be 
reproduced, transmitted, transcribed, stored in a 
retrieval system, or translated into any language or 
computer language, in any form or by any means, 
electronic, mechanical, magnetic, optical, chemical, 
manual or otherwise, without the prior written 
permission of Digital Research Inc., 60 Garden 
Court, Box DRI, Monterey, California 93942, 

DISCLAIMER 

DIGITAL RESEARCH INC. MAKES HO REPRESENTATIONS OR 
WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND 
SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF 
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR 
PURPOSE. Further, Digital Research Inc. reserves 
the right to revise this publication and to make 
changes from time to time in the content hereof 
without obligation of Digital Research Inc. to 
notify any person of such revision or changes. 

NOTICE TO USER 



"README.DOC" file. This file explains variations 
from the manual which do constitute modification of 
the manual and the items included therewith- Be 
sure to read this file before using the software. 

TRADEMARKS 

CP/M and Digital Research and its logo are 
registered trademarks of Digital Research Inc. CP/M 
Plus, LINK-80, MAC, MP/M, PL/I-80, RMAC, SID, TEX, 
and XREF are trademarks of Digital Research Inc. 

Corporation. Microsoft is a registered ttademarlt of 
Microsoft Corporation. 



The CP/M P. 


lui 


s Ope, 


rati 




Sya 


ten Command S 


umma: 


^\ 


prepai 
Formal 
Americ 


red 


" 


mg 1 
nd p; 

Firsi 


the 
; Ed 






al Research 
1 the United 

March 1984 


Stat 





Table of Contents 

How to Enter a CP/M Plus Command 1 

CP/M Plus File Specifications 1 

Command Summacy Conventions 2 

Control Characters 3 

COPYSYS 5 

DATE 6 

DEVICE 7 

DIR 10 

DUMP 15 

ED 16 

ERASE 19 

GENCOM 20 

GET 22 

HELP 24 

HEXCOM 25 

INITDIR 26 

LIB 27 

LINK 30 

MAC 33 

PATCH 35 



REKAME . 



SAVE . 



Table of Contents 
(continued) 



SETDEF 51 

SHOW 53 

SID 55 

SUBMIT 59 

TYPE 61 

USSR 62 

XREF 63 



CP/M Plus Command Summary 



HOW TO ENTER A 
CP/M PLUS COMMAND 



To give CP/M Plus a command, type a 
compiete command line following the CP/M 
Plus system prompt, A> . A CP/M Plus 



i RETURN or ENTER 



A>COMHAn} <RET> 



CP/M PLUS FILE SPECIFICATIONS 



CP/M Plus identifies eveiy file by its 
complete name ot file specification, fl 
file specification is any valid 

filename, filetype, and password, all 
separated by their appropriate delimiters, 
A drive letter must be followed by a 
colon. A filetype must be preceded by s 
period, A password must be preceded by a 
semicolon. The term filespec is ar 
abbreviation for file specification. 



designate the pai 
Symbol 



can be any single 
followed by a colon. 



i Command Suimnary 







characters; sepacated fcom 
the filename by a period. 
A period does not precede 
the filetype when the 
filetype is named alone in 
the text of this command 


; password 




The optional password, 
which can be from to 8 
alphanumeric characters; 
separ a ted from the 
filetype by a semicolon. 


Valid con 
filespec 


ibina 


tions of the elements of a 
shown below; 


• fi 

• d: 


iename 
filename 



• filename. typ 

• dif ilename. typ 

■ filename; password 

• d:f ilenameipasawocd 

■ filename. typ; password 

« d : filename. typ; password 



COMAAAND SUMMARY CONVENTIONS 



The cosnand summary alphabetically lists 
each CP/M Plus command using the following 
special symbols to define conmand syntax: 

Symbol Meaning 

1) optional itom 

I 'or' ban separats* choic*a whan 
only on* option can ba usad at a 

tlma 

n number 

CTRL control kay 

o option or an option list 

<ltBT> RETURN or ENTER kay 



CP/M Plus Command Summacy 

RH Read/Hi ite 

BO Read/Only 

SYS System attribute; file does 

appear when dicecCocy 
displayed by DIR 

DIR Directory attribu 

in response Co □: 



wildcacd; replaces all or part 
a filename and/or filetype; n 
be last character in filename 

wildcard; replaces any sir 
character In the same positior 
a filename and/or filetype 



Certain CP/M Plus commands can be modified 
by options added to the command or file 
specification. Options are enclosed in 
square brackets. The right-hand square 
bracket is optional. Only one or two 
characters of the option word are 
necessary to specify an option. 

together, separated by commas or spaces in 
the square brackets. This does not apply 



CONTROL CHARACTERS 



The following He 



CTRL-A Moves cursor one character to 
the left. Works only if your 
computer has bank-switched 

CTRL-B Moves cursor from beginning to 
end of command line and back 
without affecting command. 



CP/M Plus Cornraand Sammacy 



CONTROL CHARACTERS (continued) 



CTBL-C Stops executing progcam wh 
entececS at the system prompt 
after CTRL-S. 



CTRL-H Delete character to the left of 

CTRL-I Same as the TAB key, 

CTRL-J Moves cucsoi: to the ie£t of the 

to CI 
effec 

CTRL-K Deletes character at cursor and 
all characters to the right. 

CTRL-M Same as RETURN, 

CTRL-P Echoes console output to the 
list device. 

CTRL-Q Restarts screen scrolling. 

CTRL-R Retypes the characters to the 
left oE the cursor on a new 
line; updates the command line 
buffer. 

CTRL-S Stops screen scrolling. 

CTRL-U Updates the command line buffer 
to contain the characters to 
the left of the cursor; deletes 



of line. CTRL-J,-M,-R,-U and 
RETURN update the command line 
buffer for recall with CTRL-W. 
Banked system only. 



CP/M Plus Cocnmand Summary 

COPYSYS 



Syntax : 

COPYSYS 



COPYSYS copies the CP/M Plus system fee 
CP/M Plus system diskette to anot 
diskette. The new diskette must have 



Exaaple: 

A>COP]fSYS 



1 Command Summary 



DfiTE 

DATE C 

DATE CONTINUOUS 

DATE time-spec ific 

DATE SET 



The DATE . 
the date 


command lets ; 
and time of c 


Sxaaplea: 




A=DATE 




Displays 


the current c 


A>DATE C 




Displays 


the date and 



you display and £ 



A>DATE 0a/14/S2 1D:30:0 

Sets the date and time. 

A>DATB SET 

Prompts for date and timi 



n 

DEVICE 



CP/M Plus Command Summary 



DEVICE 
DEVICE NAMES 
DEVICE VALUES 

DEVICE logical-dev IXON | NOXON | baud-rate] 
DEVICE phyaical-dev [XON | NOXON | baud-rate) 
DEVICE logical-dev=physical-dev loptionj 
l,physical-dev {option},,,,} 
DEVICE logical-dev = NULL 
DEVICE CONSOLE [PAGE] 
DEVICE CONSOLE [COLDMNS=n, LIKES=nl 



:ent logical dei 



A>DEVICE VALUBS 

Displays the current logical devil 



A>D2VICB CRT 



A>[1BVICE CON 



CP/M Plus Command Sammary 



DEVICE (continued) 



e that the physj 
differ from 

valid devici 
■ valid devic 



speed of a peripheral de\ 



J the XON/XOFF 



baud-iate 



device 


is ready 


to leo. 


The 
folio* 


e speed a 
system 
(ing baud 


.f the 
accep 
rates: 


50 

laao 

7200 


75 
300 
2400 
9600 


110 
600 
3600 
19200 



=I,PT,CRT 

■ printer (LPT:) and the 



A>DBVICE ADXIH:-CRT2 [XOK,S 

Assigns the auxiliary logics 
(AUXIN I ) to the physical 
using pcotocol XOH/XOFF, 
CransmiBSion rate for the di 



A>DSVICB L8Tt=IinU. 



! list output logit 



A>DEVICB LPT [XOK,9GI)0] 

Seta the XON/XOFF pro 



CP/M Plus Command SummaEy 

DEVICE (continued) 

DEVICE displays oE seta the 

ExaHples: 

A>DEVtCE COHSOLB [PAGE] 



A>DEVICE CONSOLE [COLDIOIS-40,LIHE5=ie| 

Sets the screen size to 40 columns and 16 



CP/M Plus Command Sun 



The DIR 



and DIRS commands display the 
names of files cataloged in the directory 

haue the Directory (DIR) attribute. DIRS 
lists the names of files in the current 
directory that have the system (SYS) 
attribute. DIR and DIRS accept the * and 
? wildcards in the file specification. 

The DIR command with options displays the 
names of files and the characteristics 
associated with the files. 

DIR and DIRS are built-in utilities. DIR 
with options is a transient utility and 
must be loaded into memory from the disl^. 



A>DIR B: 

Displays all DIR file£ 



2A>DIR C:ZIPPY.DAT 



4A>DIR *.BAS 

Displays all DIR files 



with filetype BAS 



CP/H Plus Command Summary 



DIR (continued} 



B3>DIR ]C*,C7D 

Displays all DIR files in usee 3 on drive 
B whose filename begins with the letter X, 
and whose thr ee-cha cac te i filetype 
contains the ficst character C and last 



A>DISS *.CCM 

Displays all SYS files with £iletype COM 
on drive ft tn user 0. A command [COM) 
file in user with Che system attribute 
can be accessed from any user number on 
that drive, and from any drive in the 
search chain (see SETDEP) . 



The DIR command with options is an 
enhanced version of the DIR built-in 
command and displays your files in a 
variety of ways. DIR can search for files 
on any or all drives, for any or aJ.1 user 
numbers. One or two letters is sufficient 
to identify an option. You need not type 
the right square bracket. 

DIR Options: 

Option Function 

ATT 

Displays the user-definable file 
attributes. 

DATE 



DRIVB-(A,B,C P) 

Displays file: 
specified. 



CP/M Plus Command Summacy 



DIR (continued) 



option Function 

DRIVB»d 

Displays files on the drive 
specified by d. 

EXCLUDE 

Displays files that DO not match 
the files specified in the command 



Sends an initial form feed to ' 
printer device if the printer I 
been activated by CTRL-P. 



iza 


-byte 


records 


, and 


att 


ribj 


tea of 


the 


files 


. If there 


is a 


dir. 




label on 


Che dr. 


tve. 


DIR 


shov 




pae 


■ sword 


protec 






id the 




amps. 


If 


the 






dir 


ectocy label, 


DIR 


dij 


iplaya two 


fil 




■ ries on 


a 1 






Ltting 


thi 




isword 


and 






stamp 


CO 


luran 


a . T 




dis 


pla 


y i" 


alp 


ihabet 


ically 






(Se 


,e SET 


fOi 




descr. 


ip t i 




of 


file 




^r Ibu' 


tea, d 




tory la 


bela, 


pas 


sword! 


3 and pr 


oteci 


tlon 


modes.) 



Displays n lines of printer output 
before inserting a table heading, 
n ia a number between 5 and 65536. 



MESSAGE 

Di 


.splays the names 
ier numbers DIR is 


of 
sea 


drives am 
rching. 


MOPAGE 

Continuoui 
on the SCI 


sly scrolls 


I Inl 


rormatlon b; 


NOSORT 

Dj 
fi 


.splays files in 
.nds them on the d: 


th 


e order i( 



SIZE 

Displays the filename and : 
kilobytes (1024 bytes). 



CP/M Plus Coiwnand Summary 

DIR (continued) 

Option Function 



Diaplays all files in all ui 
numbers for Che default 
specified drive. 



nSBB-(0,l 15] 

Displays files undej 
numbers specified. 



»DIR C: IFUIjL] 

lisplays full set of characteristics for 



A>DIK Ci [DATE] 



ft>&IB Di [HI 



3A>DIR IDSER-AU., DRIVB-ALL) 



B6>DIIt [EXCLDDE] '.DAT 



3?DIR [5IEB] '.PLI •.CCM •.ASM 

LSplays all ttie files of type PLI , COM, 



CP/M Plus Command Summary 

D!R (continued) 

A>DIR (DRIVE-AU. USER-ALL] TBSTFILE.BOB 

DIR displays the fil 
it is found on an 
number . 

A>DIR [SISB.RM] D: 

DIR lists each Read/Write file that 
resides on Drive D, with its size in 



CP/H Plus Command Suramary 

DUMP 



Syntax: 

DUMP filespec 



A>D[IMP ABC.TBX 



CP/M Plus Command Summary . 



Character file editor. To redirect or 
rename the new version of the file specify 
the destination drive or destination 
filespec. 



ED COMHand Sumtary: 

Ccmmand 



append n lines from original file t 



nC, -nC 

move CP n characters forward (C) 
back {-O through buffer 

delete n characters before [-D) 
from (D) the CP 



iave new file and 



CP/M Plus Command Summary 

ED (continued) 



(kill) n lit 



nL, -nL, OL 

move CP n lir 



and display that 



execute command Chcough line n 



return to ociginal tile 

nP, -nP 

move Cp 23 lines forward and display 
23 lines at console 



read XSSSSSS?.LIB file i 

R£ilesp«c'Z 

read Eilespec into bufft 

Sdelete-string'Z insert-string 

substitute string 

nT, -nT, OT 

type n lines 

u, -n 

uppercase translation 

V, -V 

line numbering on/off 

OV 

display free buffer spac 



CP/H Plus Command Summary 

ED (continued) 

Command Action 

nW 

write n lines to new file 

OW 

write until buffer is half empty 



nXf ileapec''Z 

write n lines to filespec; append if 
previous xcommand applied to same 



delete file X$SSSSSS.LI1 



Rote: CP points to the current character 
being referenced in the edit buffer. Use 
CTRL-Z to separate multiple commands on 
the same line. Your screen displays 'Z. 



CP/H Plus Command San 



ERASE 



SRASE 

ERASE fileapec 

ERASE Eilespec (CONFIRM) 



The ERASE command cemaves one or moce 
files from the directory of a diak. 
Hlldcard characters are accepted in the 
fileapec. Directory and data apace ate 
automatically reclaimed for later use by 
another file. The ERASE command can be 
abbreviated to ERA, 

[CONFIRM] option informs the system to 
prompt for verification before erasing 
each file that matches the filespec. 
CONFIRM can be abbreviated to C. 



Bxa^l«e : 

A> ERASE X.PAS 

Removes the file X.PAS from the disk in 
drive A. 

A>SRA *.PKH 

ERASE ".PRN [Y/N) 7Y 



S>RRA AeHZ*.* [CtntFIRMl 

Each file on drive A with a filename that 
begins with MY is displayed with a 
question mark foe confirmation. Type Y to 
erase the file displayed, N to keep the 
file. 



A>HRA B:*.* 

ERASE B:*,* (Y/N) ?T 

All files on drive B a 
disk. 



CP/M Plus Command Summary 

GENCOM 



Syntax: 

GENCOH COM-fllespsc RSX-fllaspec.RSlt-filaapac 
I [LOADER I SCB- (offset, value)]} 

GEUCOM RSX-filespec ... RSX-filespec 

I [NULL [ SCB-(off3eC,value) J| 

G£NCOM filename 

GENCOM filename |SCB= (of f set .value) 1 



The GENCOM command attaches HSX files to a 
COM file, or creates a dummy COM file 
containing only RSXs. It can also restore 
a previously GENCOMed file to the original 
CCM file without the header and RSXs, add 
or replace RSXs in already GENCOMed files, 
and attach header records to COM files 
without RSXs. 

GEHCCH Options: 



HULL 

Indicates that only RSX files are 
specified, GENCOM creates a dummy 
COM file for the RSX files. The 
output COM filename is taken from 
the filename of the first RSX- 

5CB-(o£f set, value) 

Sets the System Control Block from 
the program by using Che hex values 
specified by (of fset, value) . 



Exaaples: 

A>GEHCOM HYPROG PROGl PItOG2 



CP/M Plus Comniand Summary 



GENCOM (continued) 



A'GBHCOM PKOGl PROG2 (NULL] 

l.COM with RSX's 



A>GENCOH HYPROG 

GENCOM takes MYPS0G.COM, strips otf the 
header and deletes all attached RSX's to 
restore it to its original COM format. 



A>GENCOH MYPROG PROGl PR0G2 

GENCOM looks at the already-GENCOMed file 
MY PROG. COM to see if PROGl. RSX and 
PROG2.RSX are already attached RSX files 
in the module. If either one is already 
attached, GENCOM replaces it with the new 
RSX module. Otherwise, GENCOM appends the 
specified RSX files to the COM file. 



i Command Sun 



GET (CONSOLE INPUT from) FILE filesE 
GET (CONSOLE INPUT FROM} CONSOLE 






GET direc 
command c 



the system to take console 

file for the next system 

sec program entered at the 



Console input is taken from a file until 
the program terminates. If the file is 

terminated, the pcogram looks Eor 
subsequent input from the console. If the 
program terminates before exhausting all 

console foe console input. 



Specifies that i 


Inpu 


It is echoed 


to the console. 




rhis is the 


default option. 






Specifies that fi 


lie 


input is not 


echoed to the 




isole. The 


program output 


and 


the system 


prompts are nc 




affected by 


this option a 


ind 


are still 


echoed to the cc 




lie. 


Specifies tha 


t ( 


Lhe system 


immediately go t 




le speclfiea 


file for conso] 




input. The 


system reverts 




the console 




it 




end of file. You c 


:an redirect 


the system to t 


he 


console for 


console input 


wi 


th the GET 


CONSOLE INPUT 


FHOM CONSOLE 



command lii 



CP/M Plus Command Summary 

GET (continued) 

Examples: 

A>GET PILE XINPUT 

A>HYPItOG 

Telia the system to activate the GET 
utility. Because SYSTEM is not specified. 



HYPROG progcam cequires console inpu 
is taken from the file XINPUT. 
MYPROG tecminatea, the system cevects 
to the console fotr console input. 


t, it 
When 
back 


A>GET FILE XIII2 ISYSTEM] 




Immediately directs the system to get 
subsequent console input from file XIN2 
because it includes the SYSTEM option. 
ITie system cevetta back to the console for 
console input when it reaches the end of 
file in XIN2. Or XIN2 can redirect the 
system back to the console if it contains 
a GET CONSOLE command. 



Tells the system to get console input from 
the console. This command can be used in 
a file IpreviOQSly specified in a GET FILE 
command), which is already being read by 
the system for console input. It is used 

console before the end of file is reached. 



CP/H Plus Command Sununary 



HELP 

HELP topic 

HELP topic SLibtopic 

HELP topic [NOPAGE} 

HELP topic subtopicl. . .Bubtopica 






HELP displays a lisE oE topics and 
proyides sjramarized information for CP/M 
Plus commands . 

Typing HELP topic displays information 
about that topic. Typing HELP topic 
9ubcopic displays information about tbat 

One or two letters is enough to identify 
the topics. After HELP displays 
information for youc topic, it displays 
the special prompt SELF> on your screen, 
followed by a list of subtopics. 

• Enter 7 to display list of main topics. 



A>HELP 
A>HELP DATE 
A>HELP DIR OPTIONS 
A>BELP>. OPTIONS 



CP/M Plus Command 


Summary 




HEXCOM 








Syntax: 








HEXCO« f 


lename 






Purpose : 








The HEXCOM Command gen 
file (filetype COM} from 
ic names the output fi 
filename as the inpu 
filetype COM. HEXCOM a 
file with filetype HEX. 


erates a cc 
a HEX input 
le with the 
t file but 
.ways looks 


file. 
for a 


Enable: 








A>HHXCOM 


B: PROGRAM 






Generates 


a command file 


PROGRAM. COJ- 


from 



lex file PROGRAM. HEX ( 



CP/M Plua Command Summary 

INITDIR 



INITDIR d! 



The IMTDIR command initializes a disk 
directory to allow date and time stamping 
of £ilea on that disk. INITDIR can also 
recover time/date directory space. 



INITDIR WILL. ACTIVATE TIME , 
SPECIFIED DRIVE. Do you want tc 
the directory C: (Y/N)7Y 



C?/H Plus Command Summacy 



LIB filespec loptionsl 

LIB filespec loptions) =f ilespec <inodifii 
^ , f ileBpec<[iiod if i6r> ... ] 



A library is a file that contains a 
collection of object modules. Use Che LIB 
utility to create libraries, and to 
append, replace, select, or delete modules 
from an existing library. Use LIB to 
obtain information about the contents of 
library files. 

LIS creates and maintains library files 
that contain object modules in 
Microsoft" RSL file format. These modules 
are produced by the Digital 
Research* relocatable macro-assembler 
program, RMAC", or any other language 
translator that produces modules in 
Microsoft REL file format. 

You can use LINK-BO" to link the object 
modules contained in a library to other 
object files. LINK -BO automatically 
selects from the library only thosB 
modules needed by the program being 
linKed, and then forms an executable file 
with a Eilotype of COM. 



The INDEX option creates 
an indexed library file of 
type IRL, LINK-SQ 

searches faster on indexed 

nonindexed libraries. 

The MODULE option displays 
module names. 

The PUBLICS option 
displays module names and 
the public variables for 
the new library file. 

The DUMP option displays 
the contents of object 
modules in ASCII form. 



CP/H Plus Command Summary 

LIB (continued) 



command line to 



LIB HodifieEB: 

Modifier Meaning 

Delete <iiodule'°> 

Seplace <nodule=£ilename.R£L> 

If module name and fil 
the same, you can 
following Bliorchand : 

Select [modFIRST-modLAST.modl . 

Exiumplea: 

A>LIB TEST4[P] 



A>LIfi TESTS IP) -FILB1,FILE2 

Creates TESTS. REL from Tl 
FIL.E2.SEL and displays all 
publics in TESTS. REL. 



A>LIB TB5T=TEST1(H0D1,H0D4) ,TEST21C1-C4, 

C6) 

Creates a library file TEST. REL from 
modules in two source files. TESTl.REL 
contributes MODI and M0D4 , LIB extracts 
modules CI, C4, and all the modules 
located between them, as well as module C6 
from TEST2,REL. 



A>LIB FILE2-FILE3<MODA'': 

Creates 
MODA, \ 

A>LIB FILEe=FlLe5<H0DA=PII.EB.I 



CP/H Plus Command Summary 



LIB (continued) 



A>LIB FILBG^FII.E5<THI5NAHE> 

Module THIS»AME is in FILES. REL. When LIB 
creates FH.E6.REL from FILES, REL, the file 
THISNAME.REL replaces the similarly named 
module THISNAME. 



Creates FILEl.IRL on drive A from the 
selected modules PLOTS, FIND, and modules 
SEARCH through the module DISPLAY, in 
FILE2.aEL on drive B. 



CP/H Plus Comnand SummaEy 

LINK 



UHK fileapec loptians} 

LINK lileapeo toptiotis} , . . . fileapec {optj 

LINK filBOpee loptione J=t ilaspec loptioni 



LINK combines reiocacaDle object monales 
aucii as thooe proaueed by RMAC and PL/I- 
eO" into a COM file ready for execution. 
Relocatable files con contain external 
references and publics. Relocatable tilee 
can reference isoduies in library files. 
LINK searches the library files and 
includes the referenced maOules in the 
output file. See the programii 



Operating Systeoa 1 
aSscription oF LrHk-St). 

Use LINK option swit< 

the file specifications 

ace •eparated by commsa. 

bunt-BO optional 



[05 link in banked CP/K Plus 
^stem. Aligns data segment on 
ige boundary. Puts length of 
>de segment in header. Defaults 
> SPR filetype. 

ita origin; sets Deinoiy origin for 
muaon and data area. 

>i set start address to label n. 



r MP/M'" modules, 



NO symbol table fiJ 



CP/M Plus Coininand Summary 

LINK (continued) 



Output COM command file. Default. 



OP 


Output PRL page relocatable file 
for execution under MP/M in 
relocatable segment. 


OR 


Output RSP resident system process 
file for execution under MP/M, 


OS 


Output SPR system page relocatable 
file for execution under MP/M. 


Phhhh 


Program origin; changes default 
program origin address to hhhh. 
Default is OlOOH. 


Q 


Lists symbols with leading question 



Search preceding file as a librar 
Destination of console messages, 
or Z (zero output) . Default is 
Source of intermediate files; d 



Destination of object file; d can 
be Z or disk drive A-P. Default 
is to same drive as first file in 
the LINK-BO command. 

Destination of symbol file; d can 
be Y or E or disk drive A-P. 
Default is to same drive as first 
file in LINK-80 command. 



CP/M Plus Command Sun 



LINK (continued) 



A > LINK biMYFILECKR] 



MYFILE.REL on drive B and produces the 
executable machine code file KYFILE-COM on 
drive B. The [»R] option apecifieB no 
symbol table file. 



h>LIHK ■1.»2.m3 

LINK-80 combines the separately compiled 
f ilea ml . iii2, and iii3 , resolves theic 
external refers 
executable machii 



A>I.1JK ■=^1,b2,b3 

I.INK-80 ooobineB the separately compiled 
files ml, m2, and m3 and pcoduces the 
executable machine code file m.COM. 



A>LIIK HYFILE.FILEBCb] 



The [a] option tells 


LINK-BO tc 


FILE5 as a library. 


LINK-80 I 


MYFILE.REL «ith the ref 


erenced subi 




lEL on the 


drive A and produces 1 


WYFILE.COM ( 



CP/K Plus Command Summacy 



MAC-, Che CP/M Plus macro assembler, reads 
assembly language statements from a file 
of type ASM, assembles the atatementa, and 
produces three output files with the input 
filename and filetypes of HEX, PRN, and 
SYM. F i 1 e n ame . HEX contains 
Intel' hexadecimal focmat object code. 
Filename. PRN contains an annotated source 
ting that you can print or examine at 



the con 


sole. 


Filename 


SYM 


:onta 


ns a 


sotted 


list o 


f symbols 


defi 


ed i 


the 


program. 












Use options to direct the 


input 


and o 


utput 


of MAC. 


Use a 


letter wi 


h the 


opti 


on to 


indicat 


e the 




nd destination 


delves, 


and c 


onsole, p 


inte 






output. 


Valid 


dcive nam 




A th 


rough 


0. X, P 


and Z 


specify console 


, pii 


nteL, 


and zero 


outpu 


, respect 


vely 







source drive for ASM file (A-0) 

destination drive for HEX file 
(A-0, Zl 

source drive for macrolibrary 
LIB files called by the MACLIB 



try LIB files 

J listing [default) 



CP/H Plus Command Summai 



MAC (continued) 



appends symbol file to print 
file 



Examples: 

A>HAC SAMPLE 

MAC assembles the file SAMPLE. ASM. 

A>HAC SAMPLE $PB AA HB SX -M 

In tfiis example, Che option list directs 
the PRN file to drive B: , obtains the ASM 
file from drive A:, directs the HEX file 
to drive B: , the SYM file to the console, 
and suppresses all macro lines during 
assembly. 



CP/M Plus Command SunmiaEy 

PATCH 



Syntax: 

PfiTCH filename!. typ} n 



The PATCH command displays or Installs 
patch numbec n to the CP/H Plus system or 
oonmiand files. The patch number n must be 
between 1 and 32 inclusive. 



A> PATCH SHOW 2 

Patches the SH0W.COM system file witi 



CP/M Plus Command Summary 
PIP 



PIP dii lGnJl-£ilespecloptionsi 

PIP £ilesp6c( I Gnl)=f lie spec I options) I , ...) 

PIP Elleapeci [Gn] ) IdBVice-fileapect optional |i3evic 



Purpose : 

The file copy prograra PIP copies files, 

other devices attached to your computet . 
The first f ilespec is the destination. 
The second filespec is the source. Use 
two or more source filespecs separated by 
commas to combine two or more files into 

available options. The IGn) option in the 
destination filespec tells PIP to copy 
your file to that user number. PIP with 
no command tail displays an * prompt and 
awaits your series o£ commands, entered 
and processed one line at a time. The 
source or destination can optionally be 
any CP/M Plus logical device. 



BzaiqpleB: 



COPY A FILE FROM ONE DISK TO ftKOTHER 

A>PIP b:'a:draft.txt 
A>PIP b:dra£t.txt = a: 
B3?PIP my£ile.dat=A: [G91 
A9>PIP B:|G31'°Byfile.dat 



COPY A FILE AND RENAME IT 



COPY MULTIPLE FILES 
i:-dtaEt.* 



CP/M Plus Command Sun 



PIP (continued) 



COMBINE MULTIPLE FILES 

A>PIP b:new.dat='fllel.dat, flle2.dat 

COPY, RENAME AND PLftCE IN USER I 
A>pip newdEa£t.txt[gl]-oldraft.txt 

COPY, REMAME AND GET FROM USER 1 
A>PIP newdraft.txt-oldraft.tztlgl] 

COPY TO/FROM LOGICAL DEVICES 

A>PIP b:funfile.Bue=c:on: 
A>PIP lst:=con: 
A>PIP I6t!=b:dra£t.txt[t8) 
A>PIP r 



Acch 
have 
last 


bee 
copy 


Copy or 
Chang 


ly 
ed 


Conf 
conf 
copy 


irm. 


PIP 
on bef 


n 


Delete a 


ny cha 


rac 



forra-feeds frt 



Lid Hex format. 



r output 
ct f i le 



CP/M Plus Conunat 



PIP (continued) 


PIP Options t 




Option 


Functic 


Qb'Z 
R 


Quit copying £i 
string s. 
Read Eilea that 
Co SYStem. 


Ss'Z 


Statt copying Ec 
at the string s. 


Tn 


Expand tabs to n 



1 the pacity bit, 



All options except C, Gn, K, 0, R, V, and 
M force an ASCII file tranafec, ehf---^-- 
by character, terminated by a 'Z. 



CP/K Plus Command Summary 



PUT CONSOLE loUTPUT TO) FILE flleapec ■ 

PUT PRIMTER [output TOJ FILE fileapec 

PUT CONSOLE [output To] CONSOLE 

PUT PRINTER (output TO) PRINTER 



PUT puts cor 
file for the 
console, unt 



pcogcam termii 

console. Printer output is directe 
file until the program terminates. 

POT with the SYSTEM option direct 
Bubsequent console/printer output 
specified file. This option term, 
when you enter the PUT CONSOLE c 
PRINTER command. 



console. 

i output t 



Escape character is t 



HO riLTBR Mean 



I that PUT does nc 
Late control oharactert 
ls the default option. 



CP/M Plus Conunand Summary 



PUT (continued) 

POT Options: 



Option 
SXSTOi 



systen 






and ptrogci 
to the file "specified by 
filespec. Output is written to 
the file until a subsequent 
PUT CONSOLE c .... 



outpu' 



the 



Exaaples: 

A>PDT CONSOLE OOTPIJT TO FILE XODT [ECHO] 

Directs console output to file XOUT with 
the output echoed to the console. 

A>PDT FiUNTBR OOTPUT TO PI1.B SOtTT 

A>MyPROG 

Directs the printer output of prog cam 
HYPBOG to file XOUT. The output is not 
echoed to the printer. 



Directs all printer output to file X00T2 
as well as to the printer (with ECHO 
option), and the PUT is in effect until 
you enter a PUT PRINTER OOTPUT TO PRINTER 
command. 



A>PDT CONSOLE OUTPUT TO CONSOLE 



A'PDT PRIMTER OOTPUT TO PRINTER 



: Command Summary 



















RENAME 


new-file 


spec=Qld-£ilespec 




Purpose: 














RENAME 
in the 

or 7 wi 


di 

fi 
idc 


s you 

^enani 
ards I 


change the name of a file 
y of a disk. To change 
s in one command use the * 
n the file specifications. 




VOQ oa 
REN. 


REN 


prorap 


ate the 


RENAME command to 
or input. 



Bxa«ple3: 

A>BEIMME NEN7ILB.BAS=OLDFILE.BAS 

The file OLDFILE.BAS change 
NEWFILE.BAS on drive A. 

A>REHAMB 

The system prompts for the foil 



'lie X.PBN is renamed to Y.PHN on drive A. 
»REH A:PIUNTS.NEH>=PKINCE.NEH 



The above command 






matching A*. TEX to 


files with 


ilena 









CP/M Plus Command Suramacy 

RENAME (continued) 

A>KEH B:NEHLIST'B:OLDLIST 

The file OLDLIST changes to NE 



as the following : 

A>REM B:NBtn.IST-OLDLIST 



\>BEH (JEHLIST=B:OI.DI.IST 



CP/M PluB Command Sut 



Syntax: 

RMAC Eilespec {opt: 



e macro assembler, 
into REL files that 
te COM files. 



RMAC options specify the dest 
the output files. Replace 
destination drive letter for 



RMAC DptliMia (d^output option p«raBeteE): 

Fd drive for REL file [A-0, Z) 

Sd drive for SXM file [A-0, X, P, Z] 

Pd drive for PRN file [A-0, x, P, Z] 

The d parameter can have the following wall 

A-0 specifies drive A-0 



A>RHAC TEST $PX SB RB 

Assembles the file TEST. ASH from drive A, 
sends the listing file (TEST. PRN) to the 
console, puts the symbol file (TEST.syM) 
on drive B and puts the relocatable object 
file (TEST. REL) on drive B, 



CP/M Plus Command Saramaci 



SAVE 



SAVE copies the contents of memocy to a 
file. To use SAVE, first issue the SAVE 
command, then run your program which reads 
a file into memory. Your program exits to 
the SAVE utility which prompts you for a 
filespec to which it copies the contents 
of memory, and the beginning and ending 



Activates the SAVE \. 



A>SID du^>.coa 

Hext, execute the progrc 



When the program exits, SAVE intercepts 
the return to the syatein and prompts the 
user for the filespec and the bounds of 
memory to be SAVEd. 

SAVE Ver 3.0 



CP/M Plus Command Summary 

SAVE (continued) 

Enter fi-Le 
exit) :d(uup2.com 

IE file DUMP2. 
system asks: 

Delete dump2.com7 Y 

Then the system ai 
memory to be saved 

Beginning hex address: IC 

Ending hex address: 400 

(Hexadecime 
DUMP2 . COM , 



CP/H Plus Conmiand i 



SET [opCionE] 
SET dj [optional 
SET filespec [optioni 
SET [option - modifii 
SET filespec [option 



and di; 



n and time 
i the file 
d/Wr ite, 
you label 
label. To 



Read/Only, DIR and SYS. 

a disk and password prot 

enable time stamping of files, you mu: 

first run INITDIR to format the dii 



BKK^les : 

SET Disk Label operat 

A>SBr [KJMB-DISBIOO) 

Labels the 
DISKIOO. 



I the default drivi 



A>SBT (PASSttORD-SECRETl 

Assigns SECRET to the disk label. 

A>SBT (PASS»DRI>-<RET>1 

Nullifiea the existing password. 



SET Password OperBtionai 

SET [PROTECT-ON] 

SET [PROTECT-OFF] 

SET filespec [PASSWORD-paaawon 

SET filespec [PROTECT-REftD] 

SET filespec [PROTECT-WKITE] 

SET filespec (PROTECT -DE LETS] 

SET filespec [PBOTECT-NONE] 

SET filespec [attribute-option 



CP/H Plus Command Summary 

SET (continued) 

Password Protection Modifiers: 



The password is required for 
reading , copying writing , 
deleting or renaming the file. 

The password is required for 
writing, deleting or renaming 
the file. You do not need a 



iword is only required 

You do not need I 
to read or modify the 

>rd exists for the file, 
can be used to delete 



SBT File Attribute Optic 



ARCHIVE -OFF 
ARCaiVE-ON 



Seta the file a 



Fl-ON|OFf 
F2=OM|OFF 



CP/M Plus Command Sunimairy 

SET (continued) 

SET File Attribute Optional 

Option Function 

F3=0B|0FF Tucns on or off I 

definable file i 
F3. 

F4=ON I OFF 

F4. 

A>SET [PH0TECT=ON] 

Turns on password protection for all the 
files on Che disk. You must turn on 
password protection before you can flsaign 
passwords to filee. 

A>SET [PROT«cr-0FF] 

Disables password protection for the filBB 

A>SBT HYFILB.TBX [PABSHORD-HYFIL] 



B'SKT •.TKX IPASSHORD-SBCKKT, PaOTBCT-NIULTB) 

Assigns the password SECRET to all the TEX 
files on drive B, Each TEX file is given 
a WRITE protect mode to prevent 
unauthorized editing. 

A>SET MYFILB.TEX |RO SYS] 

Sets MYFILE.TEX to Read-Only and SYStem. 

SBT Default password operation: 

A>5ET [DEFAnLT-paS8»ocd| 

Instructs the system to use a default 
password if you do not enter a passwocd 
for a password-protected file. 



CP/H PluB Command Summary 



SET (continued) 



SST Tl»«-atai9 Opeiationsi 



SETJdl} [CREATE-ON I OFF] 
SETldsl [fiCCESS-ON OFF] 
SETfd:) [update-on] OFF] 



and date of file 
of the last access 



Tlae and Dat« Sta^> Optior 



Turns on CREATE time stamps 
on the disK In the default 
or specified drive. To 
record Che creation tim« 
of a file, the CREATE 
option must be turned on 
before the file Is 






inly ( 



n ACCESS time stamps 
disk In the default 
lecified drive, 
and CREATE options 
itoally exclusive; 
in effect 



If you turn 
the ACCESS time stamp o\ 
dish that previousl 
CREATE time Stamp 
CREATE time stamp 
automatically turned of 



the 



UPDATE time stamps record 
the time the file was last 
modified. 



CP/H Plus Command Sumnacy 

SET (continued) 



SBT Delve Operational 



A>SET B: [RO] 

Sets drive B to Read/Onli-. 



CP/M Plus Command Sun 



SETDEF 

SETDEF (TEMPORARY-d : ] 

SETDEF dii,d:i.d=i,d!)l) 

SETDEF (ORDER- [typ i ,typl ) J 

SETDEF [DISPLAY | NO DISPLAY] 

SETDEF [PAGE | NOPAGE] 



SETDEF allows the uaer to display or 
define up Co Eouc drives for the program 
seacch ordec, the drive for temporary 
files, and the Eiletype search order. The 
SETDEF definitions affect only the loading 
of programs and/oi execution of SUBMIT 
(SUB) files. SETDEF turns on/off the 
system Display and Console Page modee. 
When on, the system displays the location 
and name of programs loaded or SUBmit 
files executed, and stops after displaying 
one full console screen of information. 



Displays current SETDEF parameters. 

-Ctl 

the drive to be used 



A>SETDBF Cl,* 

Tells the system to search for a program 
on drive C, then, if not found, search for 
it on the default drive. 



A>8STDBF [ORDBR-<SUB,C0H)] 

Instructs the system to search for a SUB 
file to execute. If no SUB file is found, 
search for a COM file. 



CP/M Plus Command Sar 



SETDEF (continued) 



A>5BTDEP [DISFIAY] 

Turns on the system display mode. The 
system now displays the name and location 
of programs loaded or submit files 



[HO DISPLAY] 

Turns off the system Display mode. 



CP/H Plus Command Sununary 

SHOW 



SHOW 

SHOW 
SHOW 


d 

d 

d 
d: 


[LftBELl 
[USERS] 
[DIRl 
; [DRIVE) 








Purpose: 










The S 
disk 


HO 
ri 


command 
ve inforin 


di 
at 


splays the 


following 



• number of free directc 



A>SHOH ISPACBl 

InsttuctE the ! 



A>SBOH B: 



A>SHOH B: [LABEL) 

Displays label informs 



CP/M Plus Command Sunwiary 

SHOW (continued) 



Displays the current user numbec and all 
the usees on drive A and the corresponding 
number of files assigned to them. 



A>SBDII [DRIVE] 

Displays the drive characteristics o£ 



CP/H Plus Command Sunutiary 



SID |pgm-f ilespec) ( ,aym-f ilespec] 



The SID- symbolic debugger allows you to 
monitor and test programs developed for 
the aOBO miccoproceasor . SID supports 
real-time breakpoints, fully monitored 
execution, symbolic disassembly , assembly, 
and memory display and fill functions. 
SID can dynamically load SID utility 

histogram facilities. 



Call to memory locati 
ia the called add 
value of the BC regi 
the value of the DE 


on from SID. 

esa; b is 
3ter pair; d 

agister pai 


DlMllsH.fl 

Display memory in he 
ia a 16-bit word fo 
start address, and 


X and ASCII 
is 'the fin 



EpgB'Eilespec ( ,BY»-f llespec} 

Load program and symbol table foi 



CP/H Plus Conmand Summary 

SID (continued) 



SID c 

Command 



ComputeB hex e 
and b where 



List 8080 mnemonic instructions, e 
is the start address, and E is the 
finish address. 



Move Memory Block, s is the start 
address, h Is the high address of 
the block, and d is the destination 
start address. 

Pass point set, reset, and display, 
p is a permanent breakpoint address; 
c is initial value of pass counter. 

Rfileepeclfd) 

Read Code/Symbols. d is an offset 
to each address. 

sCwla 

Set Memory Values, s is address 
where value is sent, and W is 16-bit 

Trace Program Execution, n is the 
number of program steps, and c is 
the utility entry address. 

T(ll}{l»l,c)) 

Trace without Call. W instructs SID 
not to trace subroutines, n is the 
number of program steps, and c is 
the utility entry address. 



CP/H Plus Command Sjmmacy 

SID (continued) 



SID c 

CottiDiand 



oWW.o)) 

Monitor Execution without Trace, n 
is the number of program steps, c Is 
the utility entry address, and W 



Display the value of the next 
available location in memory (NEXT) , 
the next location after the largest 
file read in (MSZE) , the current 
value of the Program counter (PC) , 
and the address of the end-of- 
available memory (END). 



xdlltl 

Examine/alter CPU state. f is flag 
bit C, Z, M, E or I; c ia cegietei: 
A, B, D, H, S or P. 



CP/H Plus loads SID from drive j 
memory. SID displays the t prompt v 
is ready to accept commands. 

A>B:SID SMIPLE.HEX 



SID Utilities t 

SID utilities, 
special progri 
provide additional debugging fac 



data 


collec 
ibed 


n the 


and data d 
Symbolic 


isplay 


nn 


Debu 






Hanu 










o( 



Ooetatinq Systems . 



CP/M Plus Command Summary 



SID (continued) 



The HIST utility creates a histogram (bac 
graph) showing the relative frequency of 
execution o£ code within selected program 
segments of the test program. The HIST 



The TRACE utility obtains a backtrace of 
the instructions that led to a particular 
breakpoint address in a program under 
test. Vou can collect the addresses o£ up 



n 

SUBMIT 

n — 

n 

n 



CP/M Plus Command SuTMBary 



SUBMIT 

SUBMIT Eilespeo 
SUBMIT filespec aigjn 



The SUBMIT command lets you execute i 
group (batch] of conunands ftom a SUBmit 
file (a ftle with filetype o£ SUB). 



the following 



any valid CP/K Plua command 



• any data input line 

• any program input line with par; 



The command 
characters. 


line 




nnot 


ex 


ceed 


135 


The following 11 
of lines which 
file: 


nes 


llu 
be 


ente 


e t 


in a 


iety 

SUB 


MAC si SSS4 

PIP LST:-S1.PRN(TS2 

DIR *.ASH 

PIP 


S3 


S51 









CP/H Plus Command Summary 



SUBMIT (continued) 



Bxaaples: 

A > SUBMIT 



t>SaBHIT SUBK 



A>SDBHIT AA tt SZ 

SUBMIT executes the c 
replacing all occurre 
argument ZZ and all oci 



The PRQFILE.SUB SCart-up File; 

Every time you power up or reset your 
computer , CP/M Plus looks for a special 
SDBHITfile named PROFILE. SUB to execute. 
If the file does not exist, CP/M Plus 

PROFILE. SUB file exists, the system 
executes the commands in the file. This 
file is convenient to use if you regularly 
execute a set of commands before you do 
your regular session on the computer. 



CP/M Plus Command Summary 



TYPE 

TYPE Eilespec [PAGE] 
TYPE filespec [NOPAGE] 



TYPK Options: 



[PAGE] Causes the console listing to 
be displayed in paged mode; 
that is, stop automatically 
aftec listing n lines □£ text, 
where n nocmally defaults to 
24 lines per page. 

INOPAGEl Turns off Console Page Mode and 
continuously displays a typed 
file on the scieen. 



BxaBples: 

A>TYPE MYFROG.PLI 

Displays the contents of the file 



A>T1fPE BsTHISPILB [PAGE] 



CP/H PluB Conmiand Summary 

USER 



The USER conmand sets the cur lent user 

numbec. The disk dlcectocy can be divided 
Into distinct gcoupe according to a Uaec 
Number. User numbers rang* from through 



ind changes the current user 



CP/H Plus Command Summary 

XREF 



XREF [d:] filename ISP) 



XREP'" piouides a crosa-ief erence summaiy 
of variable usage in a program, XREF 
requites the PRN and SVM files produced by 
MAC or RMAC for input to the program. The 
SYM and PRN files must have the aame 
filename as the filename In the XREF 
command tail. XREF outputs a file of type 
XRF. 



A>XREF biHYPROC 

XREF operates on 
MYPROG.PRN on dri' 
BiMYPROG.XRF. 



A>XREF b:HYPROG $P 

The SP option directs the 



NOTES 



NOTES 



NOTES 



ss 

DIGITAL 
RESEARCH' 



SID™ 

Productivity Tool 

Command Summary 



COPYRIGHT 

CopyrlsHt ©197B by Digital Rasaarcli Inc All rights 
No part of this publication mav be raptoduced, tra 



DISCLAIMER 

Digital Raseafch Inc. makas no representations or warrsntias 
with respect to the contents hereof and spBcilicallv disclaims 

Oarticular purpose Furtfier, Digital Research Inc reserves the 
right 10 revise this publlcalior and lo make changes (ram 

Digital Research (nc lo notify any person of such revision or 



trademarks ot Digital Research Inc SID and MAC 
trademarks o( Digital Research Inc Intei is a regislei 

The SID Proauctlvltv Tool Command Summary was prepa 



it Edition: 1978 ' 



SID-COMMAND SUMMARY 

STARTUP 

(1) SID 

(2) SID x.y 

(3) SID x.HEX 

(4) SID x.UTL 

(5) SID x.y u.v 

Form (1) starts SID without a test pro- 
gram, (2) loads the test program x.y (y 
is normally COM), (3) loads x.HEX in 
Intel "hex" format, (4) loads and executes 
utility x, (5) loads x.y with the symbol 
table u.v (normally x.SYM). Example: 
SID S0RT.COM SORT.SYM 



RESPONSE 

(1) # 

(2) SYMBOLS 

(3) NEXT PC END 
nnnn pppp eeee 

Form (1) indicates SID is ready to accept 
commands, (2) indicates machine code 
loaded, commencing symbol table load, 
(3) shows successful machine code and/or 
symbol load where nnnn, pppp, and eeee 
are hexadecimal values giving the next 
unfilled machine code location, the initial 
program counter, and the last free mem- 
ory location, respectively. 

LETTER COMMANDS 



A 


Assemble M 


Move 


C 


CaU P 


Pass Point 


D 


Display R 


Read 


F 


Fill Memory S 


Set Memory 


G 


Go T 


Trace 


H 


Hex U 


Untrace 


I 


Input Line X 


Examine 


L 


List Mnemonics 





COMMAND LINE 

SID reads commands from the system 
console following the # prompt. Each 
command line is based upon the command 
letter and optional symbolic expressions. 
All CP/M®line editing is available on 64 
character lines terminated by carriage 
returns. A space serves as a comma 
delimiter. SID terminates whenever 
control-C is typed. 

LITERAL NUMBERS 

SID uses the hexadecimal number base, 
consisting of the decimal digits 0-9 along 
with the hex digits A-F. Numbers ex- 
ceeding four digits are truncated to the 
right. Examples are: 

30 3F 3f FF3E F3 

DECIMAL NUMBERS 

Decimal numbers are preceded by a #, 
and consist of decimal digits 0-9, Num- 
bers exceeding 65535 are truncated to 
the rightmost 16 bits. Examples are: 
#48 #9999 #65535 #0 

CHARACTERS 

SID accepts graphic ASCII characters 
within paired strir^ apostrophes ('). 
Strings of length greater than two are 
truncated to the right. The rightmost 
character of a two character string be- 
comes the least significant byte. A one 
character string has a high order 00 byte, 
zero length strings are disallowed, and a 
pair of apostrophes within a string re- 
duces to a single apostrophe. Lower case 
letters are not translated in strings. Ex- 
amples are: 

'a' 'A' 'xy' '#"' 



SYMBOL REFERENCES 

SID symbolic expressions may involve 
symbol references when a symbol table 
is present: 

(1) .s 

(2) i&s 

(3) =s 

Form (1) denotes the address of symbol 
s, (2) denotes the 16 -bit value at .s, (3) 
denotes the 8-bit value at ,s, where s is 
a sequence of characters matching a 
symbol table element. 

QUALIFIED SYMBOLS 

SID searches for a symbol match starting 
at the first symbol loaded until the first 
symbol matches. When duplicate symbols 
exist, a qualified reference of the form: 
Sj/Sg/ . . . /s^ 

matches symbols from left to right as 
the search proceeds sequentially through 
the symbol table. An example is: 

ALPHA/GAMMA/I 

SYMBOLIC EXPRESSIONS 

Expressions consist of a left to right 
sequence of literal numbers, decimal 
numbers, character strings, and symbol 
references, separated by plus ("+") and 
minus ("-") operators. Values are added 
or subtracted, accordingly, with no over- 
flow checks, to produce the final 16-bit 
result, a leading minus, as in -x, is 
computed as 0-x. A leading plus, as in 
+x, is computed as x'+x, where x' is the 
value of the last expression tvped. A 
sequence of n +'s produces the n stack- 
ed value in the program under test (see 
the G command). Blanks are not allowed 
within expressions. Examples are given 
with individual commands. 
3 



A ASSEMBLE 

(1) As 

(2) A 

(3) -A 

Form(l) begins in-line assembly at loca- 
tion s, where each successive address is 
displayed until a null line or "." is entered 
by the operator. Form (2) is equivalent 
to (1) with assumed starting address de- 
rived from last assembled, listed, or 
traced address. Form (3) removes the 
assembler/disassembler module, discards 
existing symbol information, and disables 
subsequent A or L commands. In this 
case, machine hex code is displayed in 
subsequent traces. Examples: 

AlOO 

A#100 

A.CR.LF+5 

A&GAM1VTA+@X-=I 

A+30 

^ CALL 

(1) Cs 

(2) Cs.b 

(3) Cs,b,d 

Form (1) performs a direct call from SID 
to location s in memory, without dis- 
turbing the CPU state of the program 
under test, and is most often used with 
SID Utilities. In this case, registers 
BC=0O00, DE=O000. Form (2) calls s with 
data BC=b, DE=OO0O, while form (3) also 
fills DE=d. Examples: 

cioo 

C#4096 
C.DISPLAY 

C(&JMPVEC+=X 

C.CRLF,#34 
C.CRLF,@X,+=X 



D 

(1) 


DISPLAY MEMORY 


Ds 


(2) 


Ds,f 


(3) 


D 


(4) 


D,f 


(5) 


DWs 


(6) 


DWs.t 


(7) 


DW 


(8) 


DW,f 



Form (1) types memory contents in 8-bit 
format starting at location s for i screen 
with graphic ASCII to the right of each 
line, (2) is similar, but ends at location 
f. Form (3) continues the display from 
the last displayed location, or the value 
of the HL register pair following CPU 
state display, for i screen, (4) is similar, 
but terminates at location f. Forms (5) 
through (8) are equivalent to (1) through 
(4), but display in word format (16-bits). 
Examples: 

DF3F 

D#100,#200 

D.gamma,. DELTA+# 30 

d,.GAMMA 

DW@ALPHA,+#100 



p FILL MEMORY 

Fs,f,d 
Fills memory with 8-bit data d starting 
at location s, continuing through location 
f. Examples: 

F100,3FF,ff 
f.gamma,+#100,#23 
F@ALPHA,+=I,=X 



f^ GO TO PROGRAM 

(1) G 

(2) Gp 

(3) G,a 

(4) Gp,a 

(5) G,a,b 

(6) Gp,a,b 

(7) -G . . . 

Form (1) starts the program under test 
from the current PC without breakpoints. 
Execution is in real time. Form (2) is 
equivalent, but sets PC=p before exe- 
cution, (3) starts from the current PC 
with a bpealq)oint at location a, (4) is 
similar to (3) but sets the PC to p. Form 
(5) is equivalent to (3) but sets break- 
points at a and b, while (6) presets the 
PC to p before execution. Upon encoun- 
tering a breakpoint (or an externaUy pro- 
vided RST 7), the break address is printed 
in the form: 

*nnnn 
and the optional breakpoints are cleared. 
Forms given by (7) parallel (1) through 
(6), except "pass points" are not traced 
until the corresponding pass count be- 
comes zero (see P command). The symbol 
"+" in an expression produces the topmost 
stacked value, which is used to set a 
break following a subroutine call. Given 
that a breakpoint has occurred at a sub- 
routine, the command 
G,+ 
continues execution with a return break- 
point set. Examples: 
G100 
G100,103 
G.CRLF,.PRINT,#1024 
G@JMPVEC+=I,.ENDC,.ERRC 
G,.eprsub 
G,.ERRSUB,+30 
-G100,+10,+10 



H 



HEX VALUES 



(1) Ha,b 

(2) Ha 

(3) H 

Form (1) produces the hexadecimal sum 
(a+b) and difference (a-b) of operands. 
Form (2) performs number conversion by 
typing the value of a in the format; 

hhhh #ddddd 'c' .ssss 

where hhhh is a's hex value, dddd is the 

decimal value, c is the ASCII value, if 

it exists, and ssss is the symbolic value, 

if it exists. Form (3) prints the hex 

values for each symbol table element 

(abort with rubout). Examples: 

H100,200 

H#1000,#965 

H.GAMMA+=I,@ALPHA-# 10 

H#53 

H@x+=y-5 

I INPDT IJNE 



Initializes default low memory areas for 
the R command or the program under 
test, as if the characters c, through c 
had been read and setup at the consolS 
command processor level. Default FCB's 
are initialized, and the default buffer is 
set to the initial input line. 
Examples: 

I x.dat 

ix.inp y.out 

I a:x.inp b:y.out $-p 

ITEST.COM 

I TEST.HEX TEST.SYM 

7 



I LIST CODE 

(1) Ls 

(2) Ls,f 

(3) L 

C4) -L . . . 
Form (1) lists disassembled machine code 
starting at location s for i screen, (2) 
lists mnemonics from location s through 
f (abort typeouts with rubout). Form (3) 
lists mnemonics from the last listed, as- 
sembled, or traced location for i screen. 
Form (4) parallels (1) through (3), but 
labels and symbolic operands are not 
printed. Labels are printed in the form 

ssss: 
ahead of the lines to which they corres- 
pond. Non-8080 mnemonics are printed 
as 

??= hh 
where hh is the hex value at that loca- 
tion. Examples: 

noo 

L#1024,#1034 

L.CRLF 

L@ICALL,+30 

-L.PUBUFF+=I,+'A' 



M 



MOVE MEMORY 

Ms,h,d 



Move data values from start address s 

through address h to destination address 

d. Data areas may overlap during the 

move process. Examples: 

M100,1FF,300 

M.X,.Y,.Z 

M.GAMMA,+FF,.DELTA 

M(8alpha+=x,+#50,+100 



P PASS COUNTER 

(1) Pp 

(2) Pp,c 

(3) P 

(4) -Pp 

(5) -P 

A "pass point" is a program counter loca- 
tion to monitor during execution of a 
test program. A pass point has an as- 
sociated "pass counter" in the range 1-FF 
(0-#255) which is decremented each time 
the test program executes the pass point 
address. When a pass count reaches 1, 
the pass point becomes a permanent 
breakpoint and the pass count remains 
at 1. Unlike a temporary breakpoint (see 
G), pass points with pass count 1 stop 
execution following execution of the in- 
struction at the break address. Form (1) 
sets a pass point at address p with pass 
count 1, (2) sets pass point p with pass 
count c, (3) displays active pass points 
and counts, (4) clears the pass point at 
p (equivalent to Pp,0), and (5) clears all 
pass points. Up to 8 pass points can be 
active at any time. CPU registers are 
displayed when executing a pass point, 
with the header 

nn PASS hhhh .ssss 
showing the pass count nn and address 
hhhh with optional symbol ssss. Registers 
are not displayed if -G or -U is in effect 
until the pass count reaches 1. Execution 
can be aborted during the pass trace with 
rubout. Examples: 

P100,ff 

P.BDOS 

P@ICALL+30,#20 

-P.CRLF 



P READ CODE/SYMBOI^ 

(1) R 

(2) Rd 

The I command sets up code and symbol 
files for subsequent loading with the R 
command. Form (1) reads optional code 
and optional symbols in preparation for 
program test, (2) is similar, but loads 
code and/or symbols with the bias value 
d. The sequence: 
I x.y 
R 
Sets up machine code file x.y (y is usually 
com), and reads machine code to the 
transient area. If y is HEX, the file 
must be in Intel "hex" format. The 
sequence: 

I x.y u.v 
R 
also reads the symbol file u.v (u is usually 
the same as x, and v is normally SYM). 
The form: 

I * u.v 
R 
skips the machine code load, and reads 
only the symbol file. When a symbol 
file is specified, the response 

SYMBOLS 
shows the start of the symbol file read 
operation. Thus, a "?" error before the 
SYMBOL message indicates a machine 
code read error, while "?" following the 
SYMBOL message shows a symbol file 
read error. Examples: 

I C0PY.COM 

R 

I SORT.HEX SORT.SYM 

R 

I merge.com merge.sym 

RIOOO 

I * test.sym 

R-#256 

10 



Q SET MEMORY 

(1) Ss 

(2) SWs 

Form (1) sets memory locations in 8-bit 
format, (2) sets memory in 16-bit "word" 
format. In either case, each address is 
displayed, along with the current content. 
If a null line is entered, no change is 
made, and the next address is prompted. 
If a value is typed, then the data is 
changed and the next address is promp- 
ted. Input terminates with either invalid 
input, or a single "." from the console. 
Long ASCn input is entered with form 
(1) by typing a leading quote (") followed 
by graphic characters, terminated by a 
carriage return. The examples show un- 
derlined console input: 

SlOO 

OIOT C3 34 

0101 24 f?54 

0102 CF _ 

0103 4B "Ascii 

0108 6E -X+5 

0109 D4 . 
SW.X-H 3ir 
nm UUHD 44F 

2302 4F32 gtTAMMA 
2304 33E2 

2306 FFll 1i<-.X-i-=l-#20 
2308 348F . 



T 


TRACE MODE 


(1) 


Tn 


(2) 


T 


(3) 


Tn,c 


(4) 


T,c 


(5) 


-T . . . 


(6) 


TW . . . 


(7) 


-TW . . . 



Form (1) traces n program steps, showing 
the CPU state at each step, while (2) 
traces one step. Form (3) is used with 
SID utilities, and "calls" the utility func- 
tion c at each trace step. Form (4) is 
similar to (3), but traces only one step. 
Form (5) parallels (1) to (4), but disables 
symbols. Form (6) paraUels (1) to (4), 
but performs "trace without call" showing 
only local execution. Form (7) is similar 
to (6) with symbols disabled. Examples; 
TlOO 
T#30,.COLLECT 
-TW=I,3E03 



u 



UNTRACE MODE 



(1) U . . . 

(2) -U 

(3) UW . . . 

(4) -UW . . . 

U performs the same function as T, ex- 
cept the register state is not displayed. 
Forms (2) and (4), however, disable inter- 
mediate pass point trace (see P). U and 
T both run fully monitored, with auto- 
matic breal<s at each instruction. Execu- 
tion can be aborted with rubout. Exam- 
ples: 

Uffff 

U#10000,.COLLECT 

UW=GAMMA,. COLLECT 

12 



\f EXAMINE CPU STATE 

(1) X 

(2) Xf 

(3) Xr 

Form (1) displays the CPU state in the 
format: 

f A=a B=b D=d H=h S=s P=p i s 
where f is the "flag state," a is the 8080 
accumulator content, b is the 16-bit BC 
register pair value, d is the DE value, h 
is the HL value, s is the SP value, p is 
the PC value, i is the decoded instruction 
at p, and s is symbolic information. The 
flag are represented by dashes ("-") when 
false, and their letters when true; 
Carry Zero Minus ^ven parity 
Jnter^git carry 

Form (2) allows fl^ state change, where 
f is one of C,Z,M,E, or I. The current 
state is displayed {either "-" or the let- 
ter). Enter the value 1 for true, for 
false, or null for no change. Form (3) 
allows register state change, where r is 
one of A, B, D, H, S, or P. Symbol 
information is given at s when i refer- 
ences an address, including LDAX and 
STAX. The form "=mm" is printed for 
memory referencing instructions {e.g., 
INR M, ADD M), where mm is the mem- 
ory value before execution. Examples 
with operator input underlined: 



XM 






M 






XB 






3E04 


3EFF 




XP 






446 E 


.CRLF< 


10 



SID OTILrnES 

utilities execute with SID to provide 
additional debugging facilities. A utility 
is loaded initially by typing: 

SID x.UTL 
where x is the utility name. Upon load- 
ing, the utility is setup for execution 
with SID, and responds with: 

.INITIAL = iiii 

.COLLECT = cccc 

.DISPLAY = dddd 
where iiii, cccc, and dddd are three abso- 
lute address entries to the utility for 
(re)initializing, collecting debug data, and 
displaying collected information, respec- 
tively. The SID symbol table contains 
these three entry names. A utility is 
reinitialized by typing: 

Cmi or C.INITIAL 
The display information is obtained by 
typing: 

Cdddd or C.DISPLAY 
while data collection occurs during moni- 
tored execution usir^ the T or U com- 
mands, where the second argument gives 
the collection address. Examples are: 
Uffff, .collect 
U#1000,3403 
TW1000,.COLLECT 
UWl&GAM MA,. COLLECT 
Pass points may be set during data col- 
lection to stop the monitoring at the end 
of program areas under test. The actual 
initialization, collection, and display 
functions depend upon the particular SID 
utility. 

14 



THE HBT DTIUTY 

The HIST utility creates a histogram of 
program execution between two locations 
given during initialization. Prc^ram ad- 
dresses are monitored during U or T mode 
execution, with summary data displayed 
at any time. Upon startup or reinitiali- 
zation, HIST prompts with: 

TYPE HISTOGRAM BOUNDS: 

Respond with: 

aaaa,bbbb 
for a histogram between locations aaaa 
and bbbb, inclusive. Collect data in U 
or T mode, then display results. Output 
is scaled to the maximum collected 
value, accumulating until reinitialization. 
An example; 

sid hist.utl 

tVPE Histogram bounds ioo,aoo 

.initial = 3e03 

.collect = 3e06 

.display = 3e09 

# 1 s0rt.com sort.sym 

#^^ 

SYMBOLS 

# UFF,. COLLECT 

(register display and break) 

# C.DISPLAY 

(histogram display) 

U 1000,. COLLECT 

(display and eventual break) 

C. DISPLAY 

(updated histogram display) 

# C. INITIAL 

(histogram bounds reset) 

15 



THE TRACE UTILITY 

The TRACE utility provides a dynamic 
backtrace of up to 256 instructions which 
ended at the current break address. In- 
struction address collection occurs only 
in U or T mode. Pass points can be 
active, however, during the data collec- 
tion, and will halt execution when the 
pass count becomes 1. Initialization 
clears the accumulated instructions, col- 
lection records the instruction address in 
a wraparound buffer, and display prints 
the backtrace in decoded mnemonic form 
with symbol references and labels when 
they occur. If "-A" is in effect, only 
instruction addresses are given. In this 
ease, TRACE is loaded by typing: 
SID 

# 1 TRA CE.UTL 

#1 

ADDRESSES ONLY 



An example of normal operation: 
SID TRACE.UTL 

READY FOR SYMBOLIC BACKTRACE 
#1 IWERGE.COM MERGE.SYM 

#1? 



# "UfFF,.COLLECT 

(register display, wait, break) 

# C.D1SPLAY 

(symbolic backtrace appears) 



IMPLEMENTATION NOTES 

The SID program operates in about 6K 
bytes, and self-relocates directly below 
the BDOS (overlaying the CCP area). 
The SID symbol table fills downward from 
the base of SID. As the table fills, the 
BDOS jump address is altered to reflect 
the reduced free space. Programs which 
"size" memory using the BDOS jump ad- 
dress should not be started until all sym- 
bols are loaded. 

The "-A" command increases the free 
space by about liK bytes. Any existing 
symbol information must be reloaded af- 
ter issuing the command. 

Programs will trace up to the BDOS 
where tracing is discontinued until con- 
trol returns to the calling program. ROM 
subroutine tracing is discontinued when 
ROM is entered through a call, jump, or 
PCHL, and resumed upon return to the 
calling program in RAM. 

Use rubout to abort programs running 
fully monitored in T or U mode, and an 
externally provided restart (RST 7) when 
running unmonitored with G. 



8080 MNEMONICS 

The 8080 mnemonics which follow {repro- 
duced with permission from Intel® Cor- 
poration), can be entered directly in as- 
sembly mode (see A), and are produced 
by SID in list mode (see L). Data fields 
can consist of symbolic expressions. 
Given that "AlOO" has been typed, and 
that the symbols X, Y, and Z exist, the 
following is valid input: 



MOV 


A,B 


MVI 


A,FF 


mvi 


b,#255 


MVI 


M,'x' 


LXI 


H.'ab' 


JMP 


100 


CALL 


, .X 


JZ 


6Y 


Ixi 


h,SX+=Z 


JMP 


.X/Y+5 



Notable differences between MAC" and 
the SID "A" command are that no pseudo 
operations are allowed, operands are SID 
symbolic expressions*, labels cannot be 
inserted, and register references must be 
names, not numbers. 

*In particular, note that 
LXI H,'ab' 
fills H with 'a' and L with 'b' due to the 
nature of SID expressions, which is coun- 
ter to the MAC convention. 



C3 


JMP ■\ 


CD 


call" 


C9 


RET 


C2 


JNZ 


C4 


CNZ 


CO 


RNZ 


CA 


JZ 


CC 


CZ 


C8 


R2 


D2 


JNC 


D4 


CNC 


> DO 


RNC 


DA 


■"= VAd' °C 


CC 


> Adr D8 


RC 


E2 


JPO /*" 


E4 


CPO 


' EO 


RPO 


EA 


JPE 


EC 


CPE 


E8 


RPE 


F2 


JP 


F4 


CP 


FO 


RP 


FA 


JM 


FC 


CM . 


FS 


RM 


E9 


PCHL 











06 


MVI 


B.\ 


C6 


ADI ' 




01 


LXI 8. 


OE 


MVI 


C. 


CE 


ACI 




11 


LXl D, 


16 


MVI 


D, 


D6 


SUI 




21 


LXI H, 


IE 


MVI 


E, 


^- 11 


SBI 


>D8 


31 


LXI SP, 


26 


MVI 


H. 


ANI 






2E 


MVI 


L. 


EE 


XRI 








36 


MVI 


M, 


F6 


ORI 








3e 


MVI 


A, J 


FE 


CP\} 




09 
19 
29 
39 


DAD B 
DAD D 
DAD H 
DAD SP 


04 


INR 


B 


05 


DOR 


B 






OC 


INR 


C 


OD 


DCR 


C 






14 


INR 


D 


15 


OCR 


D 






1C 


INR 


E 


ID 


DCR 


E 






24 


INR 


H 


25 


DCR 


M 


OA 


LDAX B 


20 


INR 


L 


2D 


DCR 


L 


1A 


LDAX D 


34 


INR 


M 


35 


DCR 


M 


2A 


LHLO Adr 


3C 


INR 


A 


3D 


DCR 


A 


3A 


LDA Adr 


03 


INX 


B 


OB 


OCX 


B 


02 


STAX B 


13 


INX 


D 


IB 


OCX 


D 


12 


STAX D 


23 


INX 


H 


2B 


DCX 


H 


22 


SHLD Adr 


33 


INX 


SP 


3B 


OCX 


SP 


32 


STA Adf 



D8 - constant, or logtealarithmetlc exprMSion that evaluates 
lo ar> a bit data quanlity. 
' = all Flags (C, Z, S, P. AC) affected 



C7 


RST 





07 


RLC 




58 


MOV E,B 


CF 


RST 


1 


OF 


RRC 




59 


MOV E,C 


D7 


RST 


2 


17 


RAL 




5A 


MOV E,D 


DF 


RST 


3 


IF 


RAR 




5B 


MOV E.E 


E7 


RST 


4 








5C 


MOV E,H 


EF 


RST 


5 








5D 


MOV E.L 


F7 


RST 


6 








5E 


MOV E,M 


FF 


RST 


7 








5F 


MOV E,A 








00 


NOP 




60 


MOV H,B 








76 


HUT 




61 


MOV H.C 








F3 


Dl 




62 


MOV H,D 








FB 


El 




63 
64 
65 
66 


MOV H,E 
MOV H,H 
MOV H,L 
MOV H,M 


C5 


PUSH 


B 








67 


MOV H.A 


D5 
E5 
F5 


PUSH D 


40 


MOV 


B,B 


68 


MOV L,B 


PUSH 


PSW 


41 
42 


MOV 

MOV 


B,C 
B,D 


69 
6A 


MOV L,C 
MOV L,D 


CI 

D1 
El 
F1 


POP 
POP 
POP 
POP 


B 
D 

PSW- 


43 


MOV 


B.E 


6B 


MOV L,E 


44 


MOV 


B,H 


6C 


MOV L,H 


45 


MOV 


B,L 


6D 


MOV L.L 


46 
47 


MOV 
MOV 


B.M 
B,A 


6E 
6F 


MOV L,M 
MOV L.A 


E3 


XTHL 




48 


MOV 


C,B 


70 


MOV M,B 


F9 


SPHL 




49 


MOV 


C,C 


71 


MOV M,C 








4A 


MOV 


C,D 


72 


MOV M.O 








48 


MOV 


C.E 


73 


MOV M,E 








4C 


MOV 


C,H 


74 


MOV M,H 








4D 


MOV 


C,L 


75 


MOV M,L 


EB 


XCHG 




4E 


MOV 


CM 










27 


DAA- 




4F 


MOV 


C,A 


77 


MOV M,A 


2F 


CMA 














37 


STC+ 




50 


MOV 


D.B 


78 


MOV A,B 


3F 


CMC+ 




51 


MOV 


D,C 


79 


MOV A.C 








52 


MOV 


D.D 


7A 


MOV A,D 








53 


MOV 


D,E 


7B 


MOV A,E 








54 


MOV 


D,H 


7C 


MOV A,H 




, 




55 


MOV 


D,L 


7D 


MOV A,L 


D3 


OUT 1 


DB 


56 


MOV 


D,M 


7E 


MOV A,M 


OB 


IN 


57 


MOV 


D.A 


7F 


MOV A,A 



= only CAHHY aftecled 









Ae 


XRA 


B 


80 


ADD 


B 


A9 


XHA 


C 


81 


ADD 


C 


AA 


XRA 


D 


82 


ADD 


D 


AB 


XHA 


E 


B3 


ADD 


E 


AC 


XRA 


H 


84 


ADD 


H 


AD 


XHA 


L 


85 


ADD 


L 


AE 


XHA 


M 


86 


ADD 


M 


AF 


XRA 


A 


87 


ADD 


A 














BO 


ORA 


e 


88 


ADC 


B 


B1 


OHA 


C 


89 


ADC 


C 


B2 


ORA 


D 


8A 


ADC 


D 


83 


OHA 


E 


8B 


ADC 


E 


B4 


OHA 




8C 


ADC 


H 


B5 


ORA 


L 


8D 


ADC 


L 


B6 


OHA 


M 


8E 


ADC 


M 


B7 


OHA 


A 


8F 


ADC 


A 








90 


SUB 


B 


B8 


CMP 


B 


91 


SUB 


C 


B9 


CMP 


C 


92 


SUB 


D 


BA 


CMP 


D 


93 


SUB 


E 


BB 


CMP 


£ 


94 


SUB 


H 


BC 


CMP 


H 


95 


SUB 


L 


BD 


CMP 


L 


96 


SUB 


M 


BE 
BF 


CMP 
CMP 


M 
A 



9C 


SBB 


H 


9D 


SBB 


L 


9E 


SBB 


M 


9F 


SBB 


A 


AO 


ANA 


B 


Al 


ANA 


C 


A2 


ANA 


D 


A3 


ANA 


E 


A4 


ANA 


H 


A5 


ANA 


L 


A6 


ANA 


U 


A7 


ANA 


A 



Mr = 16 bit address 
" = all Rags except CARRY affected; 

(exception: INX & DCX affect no Flags) 



NOTES 



NOTES 



NOTES 



n 
0, 

n 

n 



COPYRIGHT 

Copyright OI9S3 Digital Research [nc. All rights reserved. No part of this publication may be repiodueed, 
transmitted, transciibed, stored in a retrieval system, or translated into any language or computer language, in 
any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without 
the prior written pennission of Digital Research Inc., 60 Garden Court, Box DRl, Monterey, California 
93942. 



DISCLAIMER 

DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO 
THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MER- 
CHANT ABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Digital Research Inc. reserves 
the right to revise this publication and to make changes from time to time in the content hereof without 
obligation of Digital Research Inc. to notify any person of such revision or changes. 



NOTICE TO USER 

From time to time changes are made in the filenames and in the files actually included on (he disiribudon disk. 
This manual should nor be construed as a representation or warranty that such files or facilities exist on the 
distribution disk or as part of the materials and programs distributed. Most distribution disks include a 
"README.DOC" file. This file explains variations from the manual which do constitute modification of the 
manual and the items included therewith. Be sure to read this file before using the software. 



TRADEMARKS 

CP/M and Digital Research and its logo are registered trademarks of Digital Research Inc. ASM, CP/M Plus, 
LINK-80, MAC, MP/M, MP/M II, and RMAC ate trademarks of Digital Research Inc. Intel is a registered 
trademark of Intel Corporation. 



n Programmer's Guide was printed in the United States of 



First Edition: January 1983 
Second Edition: April 1983 



Foreword 



CP/M* 3 is a microcomputer operating system designed for the Intel* 8080, Intel 
8085, or other compatible microprocessor. To run CP/M 3, your computer must 
have an ASCII console, which includes a keyboard and screen, or another display 
device, from one to sixteen disk drives and a minimum of 32K of memory space. To 
support additional memory beyond the 64K addressing limit of the processors listed 
above, CP/M 3 can also support bank-switched memory. The minimum memory 
requirement for a banked system is 96K. 

This manual describes the programming environment of CP/M 3, and is written 
for experienced programmers who are writing application software in the CP/M 3 
environment. It assumes you are familiar with the system features and utilities described 
in the CF/M Plus (CP/M Version 3) Operating System User's Guide and die 
Programmer's Utilities Guide for the CP/M Family of Operating Systems. It also 
assumes that your CP/M 3 system has been customized for your computer's hard- 
ware and is executing as described in the CP/M Plus (CP/M Version 3) Operating 
System User's Guide. If you need to customize your system, please refer to the CP/M 
Plus (CPIM Version 3) Operating System System Guide. 

Section 1 of this manual describes the components of the operating system, where 
they reside in memory, and how they work together to provide a standard operating 
environment for application programs. Seaion 2 describes how an application pro- 
gram can call on CP/M 3 to perform serial input and output and manage disk files. 
Section 3 provides a detailed description of each operating system funaion. Section 
4 presents example programs. 

The CP/M Plus (CP/M Version 3} Operating System Programmer's Guide contains 
five appendixes. Appendix A describes the CP/M 3 System Control Block, and defines 
its fields. Appendix B supplies the format for the Page Relocatable Program. Appen- 
dix C tells you how to generate System Page Relocatable files. Appendix D lists the 
ASCII Symbol Table, and Appendix E summarizes BDOS functions. 



Table of Contents 



1 Introduction to CP/M 3 

1.1 Banked and Nonbanked Memory Organization 1-2 

1.2 System Components 1-5 

1.3 System Component Interaction and Communication 1-7 

1.3.1 TheBDOS and BIOS 1-7 

1.3.2 Applications and the BDOS 1-8 

1.3.3 Applications and RSXs 1-9 

1 .4 Memory Region Boundaries 1-9 

1.5 Disk and Drive Organization and Requirements 1-11 

1.6 System Operation 1-13 

1.6.1 Cold Start Operation 1-14 

1 .6.2 CCP Operation 1-16 

1.6.3 Transient Program Operation 1-22 

1 .6.4 Resident System Extension Operation 1-23 

1.6.5 SUBMIT Operation 1-26 

1.7 System Control Block 1-27 

2 The BDOS System Interface 

2. 1 BDOS Calling Conventions 2-1 

2.2 BDOS Serial Device I/O 2-2 

2.2.1 BDOS Console I/O 2-3 

2.2.2 Other Serial I/O 2-6 

2.3 BDOS File System 2-7 

2.3.1 File Naming Conventions 2-9 

2.3.2 Disk and File Organization 2-11 

2.3.3 File Control Block Definition 2-13 

2.3.4 File Attributes 2-16 

2.3.5 User Number Conventions 2-18 

2.3.6 Directory Labels and XFCBs 2-19 

2.3.7 File Passwords 2-21 

2.3.8 File Date and Time Stamps 2-23 

2.3.9 Record Blocking and Deblocking 2-25 

2.3. 10 Multi-Sector I/O 2-26 

2.3.11 Disk Reset and Removable Media 2-27 

2.3.12 File Byte Counts 2-28 



Table of Contents (continued) 



2.3 . 13 BDOS Error Handling 2-28 

2.4 Page Zero Initialization 2-34 

3 BDOS Function Calls 

4 Programming Examples 

4.1 A Sample File-To-File Copy Program 4-1 

4.2 A Sample File Dump Utility 4-5 

4.3 A Sample Random Access Program 4-10 

4.4 Construction of an RSX Program 4-20 

4.4.1 The RSX Prefix 4-21 

4.4.2 Example of RSX Use 4-22 

Appendixes 

A System Control Block A- 1 

B PRL File Generation B- 1 

B. 1 PRL Format B- 1 

B.2 Generating a PRL B-2 

C SPR Generation C- 1 

D ASCII and Hexadecimal Conversions D-I 

E BDOS Function Summary E-1 



Table of Contents (continued) 



Tables 



Valid Filename Delimiters 2-10 

Logical Drive Capacity 2-12 

2-3. BDOS Interface Attributes 2-17 

2-4. Password ProtcCTion Modes 2-22 

BDOS Functions That Test for Password 2-22 

2-6. SFCB Subfields Format 2-24 

2-7. Register A BDOS Error Codes 2-31 

2-8. BDOS Directory Codes 2-32 

BDOS Error Flags 2-33 

BDOS Physical and Extended Errors 2-34 

Page Zero Areas 2-35 

Function 6 Entry Parameters 3-8 

Edit Control Characters (Nonbanked CP/M 3) 3-13 

Edit Control Charaaers (Banked CP/M 3) 3-14 

System Control Block 3-70 

Program Return Codes 3-90 

FCB Format 3-98 

SCB Fields and Definitions A-1 

B-1. PRL File Format B-1 

D-1. ASCII Symbols D-1 

D-2. ASCII Conversion Table D-2 

E-1 . BDOS Function Summary E-1 



Table of Contents (continued) 



Figures 

1. Nonbanked System Memory Organization 1-2 

2. Banked System Memory Organization 1-3 

Banked Memory with Bank 1 in Context 1-4 

CP/M 3 Logical Memory Organization 1-5 

5. System Components and Regions in Logical Memory 1-6 

6. System Modules and Regions in Logical Memory 1-10 

Disk Organization 1-12 

RSX File Format 1-25 

2-1. XFCB Format 2-19 

2-2. Direaory Label Format 2-20 

2-3. Direaory Record with SFCB 2-23 



Section 1 
Introduction to CP/M 3 



This section introduces you to the general features of CP/M 3 with an emphasis 
on how CP/M 3 organizes your computer's memory. The section begins by describing 
the general memory organization of banked and nonbanked systems and defines the 
programming environment they have in common. It then shows how CP/M 3 defines 
memory space into standard regions for operating system modules and executing 
programs. Subsequent paragraphs describe the components of the operating system, 
how they communicate with each other and the application program, and in greater 
detail where each component and program is located in memory. After a brief intro- 
duction to disk organization, the final section gives examples of system operation. 



CP/M 3 is available in two versions: a version that supports bank-switched mem- 
ory, and a version that runs on nonbanked systems. CP/M 3 uses the additional 
memory available in banked systems to provide functions that are not present in the 
nonbanked version. For example, the banked version of CP/M 3 supports file pass- 
words; the nonbanked version does not. However, because a nonbanked system 
treats passwords the same way as a banked system does when password protection 
is not enabled, an application program can run under either system without modifi- 
cation. 



B DIGITAL RESEARCH'" 



1.1 Banked/Nonbanked Organization 



CP/M 3 Programmer's Guide 



1.1 Banked and Nonbanked Memory Organization 

The memory organization for a nonbanked CP/M 3 system is very simple, as 
shown in Figure 1-1. 



TOP OF MEMORY' 



LOW MEMORY 

(OOOOH)^ 




Figure 1-1. Nonbanked System Memory Organization 



In the nonbanked organization, physical memory consists of a single, contiguous 
region addressable from OOOOH up to a maximum of OFFFFH (64K-1}. The shaded 
region below the operating system represents the memory space available for the 
loading and execution of transient programs. The clear area above the operating 
system represents space that GENCPM can allocate to the operating system for disk 
record buffers and directory hash tables, as described in the CP/M Plus (CP/M Ver- 
sion 3) Operating System System Guide. The minimum size of this area is determined 
by the specific hardware requirements of the host microcomputer system. 



m DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



1.1 Banked/Nonbanked Organization 



To expand memory capacity beyond the 64K address space of an 8-bit micropro- 
cessor, CP/M 3 supports bank-switched memory in a special version called the banked 
system. In the banked version, the operating system is divided into two modules: the 
resident portion and tbe banked portion. The resident portion resides in common 
memory; the banked portion resides just below the top of banked memory in Bank 0. 
Figure 1-2 shows memory organization under the banked system. 



TOP OF MEMORY ■ 



TOP OF BANKED ■■ - 
MEMORY 



(BANK SWITCHED) ■ 



LOW MEMORY 

(OOOOH) ». 



BANKED 

o,s. 




BANKO BANK 1 

Figure 1-2. Banked System Memory Organization 



In Figure 1-2, Bank is switched in or in context. The top region of memory, the 
common region, is always in context; that is, it can always be referenced, no matter 
what bank is switched in. Figure 1-3 shows memory organization when Bank 1 is in 
context. 



ffll DIGITAL RESEARCH'" 



1.1 Banked/Nonbanked Organizatio 



CP/M 3 Programmer's Guide 



TOP OF MEMORY ^ 



(COMMON) - 



TOP OF BANKED *. ,- 
MEMORY 



(BANKSWrjCHED) 



LOW MEMORY 
(OOOOH) * 





BANK BANK 1 . . , , BANK N 

Figure 1-3. Banked Memory with Bank 1 in Context 



From a transient program's perspective, Bank 1 is always in context, The operating 
system can switch to Bank or other banks when performing operating system 
functions without affeaing the execution of the transient program. Any bank-switch- 
ing performed by the operating system is completely transparent to the calling pro- 
gram. Because the major portion of the operating system resides in Bank in banked 
systems, more memory space is available for transient programs in banked CP/M 3 
systems than in nonbanked systems. 

The operating system uses the clear areas in Figures 1-2 and 1-3 for disk record 
buffers and directory hash tables. The clear area in the common region above the 
operating system represents space that can be allocated for data buffers by GENCPM. 
Again, the minimum size of this area is determined by the specific hardware require- 
ments of the host microcomputer system. 



m DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 



1.1 Banked /Nonbanked Orgai 



The banked version of CP/M 3 requires a minimum of two banks, Bank and 
Bank 1, and can support up to 16 banks of memory. Bank numbers are generally 
arbitrary with the following exceptions: Bank is the system bank and is in context 
when CP/M 3 is started. Bank 1 is the transient program bank, and must be contig- 
uous from location zero to the top of banked memory. This requirement does not 
apply to the other banks. However, common memory must be contiguous. 

The size of the common region is typically 16K. The only size requirement on the 
common region is that it must be large enough to contain the resident portion of the 
operating system. The maximum top of memory address for both banked and non- 
banked systems is 64K-1 (OFFFFH). 

In summary, no matter how physical memory is configured, or whether the oper- 
ating system is banked or nonbanked, CP/M 3 always organizes memory logically so 
that to a transient program in any CP/M 3 system, memory appears as shown in 
Figure 1-4, 



TOP OF MEMORY. 



LOW MEMORY 

(OOOOH) ^ 




Figure 1-4. CP/M 3 Logical Memory Organization 



1.2 System Components 

Funaionally, the CP/M 3 operating system is composed of distina modules. Tran- 
sient programs can communicate with these modules to request system services. Fig- 
ure 1-5 shows the regions where these modules reside in logical memory. Note that 
from the transient program's perspective. Figure 1-5 is just a more detailed version 
of Figure 1-4. 



H DIGITAL RESEARCH™ 



1.2 System Components 



CP/M 3 Programmer's Guide 



HIGH MEMORY: 

BIOS_BASE: 

BDOS_BASE: 

LOADER_BASE: 

RSX.BASE: 



BIOS ; BASIC INPUT/OUTPUT SYSTEM 



BDOS ; BASIC DISK OPERATING SYSTEM 



LOADER : PROGRAM LOADER MODULE 



RSX(s) : RESIDENT SYSTEM EXTENSIONS 



TPA TRANSIENT PROGRAM AREA 



CCP: CONSOLE COMMAND PROCESSOR i 



Figure 1-5. System Components and Regions in Logical Memory 



The Basic Input/Output System, BIOS, is a hardware-dependent module that defines 
the low-level interface to a particular computer system. It contains the device- driving 
s necessary for peripheral device I/O. 



The Basic Disk Operating System, BDOS, is the hardware-independent module that 
is the logical nucleus of CP/M 3. It provides a standard operating environment for 
transient programs by making services available through numbered system function 
calls. 

The LOADER module handles program loading for the Console Command Proces- 
sor and transient programs. Usually, this module is not resident when transient pro- 
grams execute. However, when it is resident, transient programs can access this 
module by making BDOS Function 59 calls. 

Resident System Extensions, RSXs, are temporary additional operating system 
modules that can selectively extend or modify normal operating system funaions. 
The LOADER module is always resident when RSXs are active. 



Q DIGITAL RESEARCH'- 



CP/M 3 Programmer's Guide 1.2 System Components 

The Transient Program Area, TPA, is the region of memory where transient pro- 
grams execute. The CCP also executes in this region. 

The Console Command Processor, CCP, is not an operating system module, but is 
a system program that presents a human-oriented interface to CP/M 3 for the user. 

The Page Zero region is not an ojierating system module either, but functions 
primarily as an interface to the BDOS module from the CCP and transient programs. 
It also contains critical system parameters. 



1.3 System Component Interaction and Communication 

This section describes interaction and communication between the modules and 
regions defined In Section 1,2. The most significant channels of communication are 
between the BDOS and the BIOS, transient programs and the BDOS, and transient 
programs and RSXs. 

The division of responsJbiUty between the different modules and the way they 
communicate with one another ptovide three Important benefits. First, because the 
operating system is divided into two modules — one that is configured for different 
hardware environments, and one that remains constant on every computer — CP/M 3 
software is hardware independent; you can pon your programs unchanged to differ- 
ent hardware configurations. Second, because all communication between transient 
programs and the BDOS is channeled through Page Zero, CP/M 3 transient programs 
execute, if sufficient memory Is available, independent of configured memory size. 
Third, the CP/M 3 RSX facility can customize the services of CP/M 3 on a selective 
basis. 

1.3.1 The BDOS and BIOS 

CP/M 3 achieves hardware Independence through the interface between the BDOS 
and the BIOS modules of the operating system. This interface consists of a series of 
entry points In the BIOS that the BDOS calls to perform hardware-dependent primi- 
tive functions such as peripheral device I/O. For example, the BDOS calls the CONIN 
entry point of the BIOS to read the next console input character. 

A system implementor can customize the BIOS to match a specific hardware envi- 
ronment. However, even when the BIOS primitives are customized to match the host 
computer's hardware environment, the BIOS entry points and the BDOS remain 
constant. Therefore, the BDOS and the BIOS modules work together to give the CCP 
and other transient programs hardware-independent access to CP/M 3's facilities. 

B DIGITAL RESEARCH'- 



1.3 Component Interaction CP/M 3 Programmer's Guide 

1.3.2 Applications and the BDOS 

Transient programs and the CCP access CP/M 3 facilities by making BDOS func- 
tion calls. BDOS functions can create, delete, open, and close disk files, read or write 
to opened files, retrieve input from the console, send output to the console or list 
device, and perform a wide range of other services described in Section 3,"BDOS 
Functions." 

To make a BDOS function call, a transient program loads CPU registers with 
specific entry parameters and calls location 0005H in Page Zero. If RSXs are not 
active in memory, location 0005H contains a jump instruction to location 
BDOS_base + 6. If RSXs are active, location 0005H contains a jump instruction to 
an address below BDOS_base. Thus, the Page Zero interface allows programs to run 
without regard to where the operating system modules are located in memory. In 
addition, transient programs can use the address at location 0006H as a memory 
ceiling. 

Some BDOS functions are similar to BIOS entry points, particularly in the case of 
simple device I/O. For example, when a transient program makes a console output 
BDOS function call, the BDOS makes a BIOS console output call. In the case of disk 
I/O, however, this relationship is more complex. The BDOS might call many BIOS 
entry points to perform a single BDOS file I/O function. 

Transient programs can terminate execution by jumping to location OOOOH in the 
Page Zero region. This location contains a jump instruction to BIOS base + 3, which 
contains a jump instruction to the BIOS warm stan routine. The BIOS warm start 
routine loads the CCP into memory at location lOOH and then passes control to it. 

The Console Command Processor is a special system program that executes in the 
TPA and makes BDOS calls just like an application program. However, the CCP has 
a unique role: it gives the user access to operating system facilities while transient 
programs are not executing. It includes several built-in commands, such as TYPE and 
DIR, that can be executed direaly without having to be loaded from disk. When the 
CCP receives control, it reads the user's command lines, distinguishes between built- 
in and transient commands, and when necessary, calls upon the LOADER module to 
load transient programs from disk into the TPA for execution. Section 1.6,2 describes 
CCP operation in detail. 



- IS DIGITAL RESEARCH- 



CP/M 3 Programmer's Guide 1.3 Component Interaction 

1.3.3 Applications and RSXs 

A Resident System Extension is a temporary additional operating system module. 
An RSX can extend or modify one or more operating system funaions selectively. 
As with a standard BDOS function, a transient program accesses an RSX function 
through a numbered function call. 

At any one time there might be zero, one, or multiple RSXs active in memory. 
When a transient progiam makes a BDOS function call, and RSXs are active, each 
RSX examines the function number of the call. If the function number matches the 
function the RSX is designed to extend or modify, the RSX performs the requested 
funaion. Otherwise, the RSX passes the funaion request to the next RSX. Noninter- 
cepted functions are eventually passed lo the BDOS for standard execution, 

RSXs are loaded into memory when programs containing RSXs are loaded. The 
CP/M 3 utility, GENCOM, can attach RSXs to program files. When attaching RSXs, 
GENCOM places a special one page header at the beginning of the program file. The 
CCP reads this header, learns that a program has attached RSXs, and loads the RSXs 
accordingly. The header itself is not loaded into memory; it merely indicates to the 
CCP that RSX loading is required. 

The LOADER module is a special type of RSX that supports BDOS function 59, 
Load Overlay, It is always resident when RSXs are active. To indicate RSX support 
is required, a program that calls function 59 must have an RSX header attached by 
GENCOM, even if the program does not require other RSXs. When the CCP 
encounters this type of header in a program file when no RSXs are active, it sets the 
address at location 0006H in Page Zero to LOADER_base + 6 instead of 
BDOS_base + 6. 



1.4 Memory Region Boundaries 

This section reviews memory regions under CP/M 3, and then describes some 
details of region boundaries. It then relates the sizes of various modules to the space 
available for the execution of transient programs. Figure 1-6 reviews the location of 
regions in logical memory. 



n . 



DIGITAL RESEARCH'" 



1.4 Region Boundaries 

HIGH MEMORY: 

BIOS_BASE: 

BDOS.BASE: 

LOADER_BASE: 



CP/M 3 Programmer's Guide 



BIOS : BASIC I/O SYSTEM 



BDOS : BASIC DISK OPERATING SYSTEM 



LOADER : PROGRAM LOADER MODULE 



RSX(1) : RESIDENT SYSTEM EXTENSION 



%■ TPA . TRANSIENT PROGRAM AREA 



RSX(N) ■ RESIDENT SYSTEM EXTENSION 



.cc, 



P ; CONSOLE COMMAND PROCESSOR '^ 



Figure 1-6. System Modules and Regions in Logical Memory 



First note that all memory regions in CP/M 3 are page-aligned. This means that 
regions and operating system modules must begin on a page boundary. A page is 
defined as 256 bytes, so a page boundary always begins at an address where the low- 
order byte is zero. 

The term High Memory in Figure 1-6 denotes the high address of a CP/M 3 
system. This address may fall below the actual top of memory address if space above 
the operating system has been allocated for directory hashing or data buffering by 
GENCPM. The maximum top of memory address for both banked and nonbanked 
systems is 64K-1 (OFFFFH). 

The labels BiOS_base, BDOS_base, and LOADERbase represent die base addresses 
of the operating system regions. These addresses always fall on page boundaries. The 
size of the BIOS region is not fixed, but is determined by the requirements of the 
host computer system. 



SI DIGITAL RESEARCH'" 



n 



CP/M 3 Programmer's Guide 1.4 Region Boundaries 

The size of the BDOS region differs for the banked and nonbanked versions of 
CP/M 3. In the banked version, the resident BDOS size is 6 pages, 1.5K. In the 
nonbanked system, the BDOS size ranges from 31 pages, 7.75K, to 33 pages, 8.25K, 
depending on system generation options and BIOS requirements. 

RSXs are page aHgned modules that are stacked in memory below LOADER_base 
in memory. In the configuration shown in Figure 1-6, location 0005H of Page Zero 
contains a jump to location RSX(N)_base + 6. Thus, the memory ceiling of the TPA 
region is reduced when RSXs are active. 

Under CP/M 3, the CCP is a transient program that the BIOS loads into the TPA 
region of memory at system cold and warm start. The BIOS also loads the LOADER 
module at this rime, because the LOADER module is attached to the CCP. When the 
CCP gains control, it relocates the LOADER module just below BDOSbase. The 
LOADER module handles program loading for the CCP, It is three pages long. 

The maximum size of a transient program that can be loaded into the TPA is 
limited by LOADER_base because the LOADER cannot load a program over itself. 
Transient programs may extend beyond this point, however, by using memory above 
LOADER_base for uninirialized data areas such as I/O buffers. Programs that use 
memory above BDOS_base cannot make BDOS function calls. 

1.5 Disk and Drive Organization and Requirements 

CP/M 3 can support up to sixteen logical drives, identified by the letters A through 
P, with up to 512 megabytes of storage each. A logical drive usually corresponds to 
a physical drive on the system, particularly for physical drives that support remova- 
ble media such as floppy disks. High-capacity hard disks, however, are commonly 
divided up into multiple logical drives. Figure 1-7 illustrates the standard organiza- 
tion of a CP/M 3 disk. 



B DIGITAL RESEARCH'" 



1.5 Disk Organization 

TRACK M - 
DATA TRACKS 
TRACK N - 

SYSTEM TRACKS 



CP/M 3 Programmer's Guide 



CP/M 3 DATA REGION 



CP/M 3 DIRECTORY REGION 



CCP (OPTIONAL) 



COLD BOOT LOADER 



Figure 1-7. Disk Organization 



In Figure 1-7, the first N tracks are the system tracks. System tracks are required 
only on the disk used by CP/M 3 during system cold start or warm start. The 
contents of this region are described in Section 1.6.1. All normal CP/M 3 disk access 
is directed to the data tracks which CP/M 3 uses for file storage. 

The data tracks are divided into two regions: a directory area and a data area. The 
directory area defines the files that exist on the drive and identifies the data space 
that belongs to each file. The data area contains the file data defined by the directory. 
If the drive has adequate storage, a CP/M 3 file can be as large as 32 megabytes. 

The directory area is subdivided into sixteen logically independent direaories. These 
directories are identified by user numbers through 15. During system operation, 
CP/M 3 runs with the user number set to a single value. The user number can be 
changed at the console with the USER command. A transient program can change 
the user number by calling a BDOS function. 

The user number specifics the currently active directories for all the drives on the 
system. For example, a PIP command to copy a file from one disk to another gives 
the destination file the same user number as the source file unless the PIP command 
is modified by the [G] option. 



a DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 1.5 Disk Organization 

The direaory identifies each file with an eight-character filename and a three- 
character filetype. Together, these fields must be unique for each file. Files with the 
same filename and filetype can reside in different user directories on the same drive 
without conflict. Under the banked version of CP/M 3, a file can be assigned an 
eight-character password to protect the file from unauthorized access. 



All BDOS functions that involve file operations specify the requested file by file- 
name and filetype. Multiple files can be specified by a technique called ambiguous 
reference, which uses question marks and asterisks as wildcard characters to give 
CP/M 3 a pattern to match as it searches the directory. A question mark in an 
ambiguous reference matches any value in the same position in the directory filename 
or filetype field, An asterisk fills the remainder of the filename or filetype field of the 
ambiguous reference with question marks. Thus, a filename and filetype field of all 
question marks, ????????.???, equals an ambiguous reference of two asterisks, *.*, 
and matches all files in the direaory that belong to the current user number. 

The CP/M 3 file system automatically allocates directory space and data area space 
when a file is created or extended, and returns previously allocated space to free 
space when a file is deleted or truncated. If no directory or data space is available for 
a requested operation, the BDOS returns an error to the calling program. In general, 
the allocation and deallocation of disk space is transparent to the calling program. 
As a result, you need not be concerned with directory and drive organization when 
using the file system facilities of CP/M 3. 



1.6 System Operation 

This section introduces the general operation of CP/M 3. This overview covers 
topics concerning the CP/M 3 system components, how they function and how they 
interact when CP/M 3 is running. This section does not describe the total function- 
ality of CP/M 3, but simply introduces basic CP/M 3 operations. 

For the purpose of this overview, CP/M 3 system operation is divided into five 
categories. First is system cold start, the process that begins execution of the operat- 
ing system. This procedure ends when the Console Command Processor, CCP, is 
loaded into memory and the system prompt is displayed on the screen. Second is the 
operation of the CCP, which provides the user interface to CP/M 3. Third is transient 
program initiation, execution and termination. Fourth is the way Resident System 
Extensions run under CP/M 3. The fifth and final category describes the operation of 
the CP/M 3 SUBMIT utility. 



IS DIGITAL RESEARCH'- 



1,6 System Operation CP/M 3 Programmer's Guide 

1.6.1 Cold Start Operation 

The cold start procedure is typically executed immediately after the computer is 
turned on, The cold start brings CP/M 3 into memory and gives it control of the 
computer's resources. Cold start is a four-stage procedure. 

In the first stage, a hardware feature, or ROM-based software associated with 
system reset, loads a small program, called the Cold Boot Loader, into memory from 
the system tracks of drive A (see figure 1-6). The Cold Boot Loader is usually 128 or 
256 bytes long. 

The Cold Boot Loader performs the second stage of the cold start process. It loads 
the CP/M 3 loader program, CPMLDR, into memory from the system tracks of the 
system disk and passes control to it. During this stage, the Cold Boot Loader can 
also perform other tasks, such as initializing hardware dependent I/O ports. 

CPMLDR performs the third stage in the cold start process. First, it reads the 
CPM3.SYS file from the data area of the disk. The CPM3.SYS file, which is created 
by the CP/M 3 system generation utility GENCPM, contains the BDOS and BIOS 
system components and information indicating where these modules are to reside in 
memory. Once CPMLDR has loaded the BDOS and BIOS into memory, it sends a 
sign-on message to the console and passes control to the BIOS Cold Boot entry point. 
If specified as a GENCPM option, CPMLDR can also display a memory map of the 
CP/M 3 system. 



CPMLDR is a small, self-contained version of CP/M 3 that suppons only console 
output and sequential file input. Consistent with CP/M 3's organization, it contains 
two modules, an invariant CPMLDR_BDOS, and a variant CPMLDR_B10S that is 
adapted to match the host microcomputer hardware environment. Cold start initiali- 
zadon of I/O ports and similar functions can also be performed in the CPMLDR_BIOS 
module during the third stage of cold start. 

In the banked version of CP/M 3, these first three stages of the cold boot procedure 
are performed with Bank in context. The BIOS Cold Start function switches in 
Bank 1 before proceeding to stage four. 



- It DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 1.6 System Op. 

The fourth and final stage in the cold start procedure is performed by the BIOS 
Cold Start function. Function 0. The entry point to this funaion is located at 
BIOS_base as described in Section 1.4. The BIOS Cold Start function begins by 
performing any remaining hardware initialization, and initializing Page Zero. To 
initialize Page Zero, the BIOS Cold Start funaion places a jump to BIOS_basc + 3, 
the BIOS Warm Start entry point, at location OOOOH, and a jump to BDOS_base + 6, 
the BDOS entry point, at location 0005H in memory. 

The BIOS Cold Start function completes the fourth stage by loading the CCP into 
the TPA region of memory and passing control to it. The CCP can be loaded from 
one of two locations. If there is sufficient space in the system tracks for the CCP, it 
is usually loaded from there. If there is not enough space in the system tracks, the 
BIOS Cold Start function can read the CCP from the file CCP.COM. 

On some banked systems, the CCP is also copied to an alternate bank, so that 
warm start operations can copy the CCP into the TPA from memory. This speeds up 
the system warm start operation, and makes it possible to warm start the system 
without having to access a system disk. 

When the CCP gains control, it displays a prompt that references the default disk. 
If a PR0F1LE.SUB submit file is present on the default drive, the CCP executes this 
submit file before prompting the user for a command. 

At this point, the cold start procedure is complete. Note that the user number is 
set to zero when CP/M 3 is cold started. However, the PROFILE submit file can set 
the user number to another value if this is desirable. 

The cold start procedure is designed so that the system tracks need to be initialized 
only once. This is accomplished because the system track routines are independent of 
the configured memory size of the CP/M 3 system. The Cold Boot Loader loads 
CPMLDR into a constant location in memory. This location is chosen when the 
system is configured. However, CPMLDR locates the BDOS and BIOS system com- 
ponents in memory as specified by the CPM3.SYS file. The CCP always executes at 
location lOOH in the TPA. Thus, CP/M 3 allows the user to generate a new system 
with GENCPM, and then run it without having to update the system tracks of the 
system disk. 



n , 



DIGITAL RESEARCH- 



1.6 System Operation CP/M 3 Programmer's Guide " 

1.6.2 CCP Operation ^ 

The Console Command Processor provides the user access to CP/M 3 facilities 
when transient programs are not running. It also reads the user's command Mnes, 
differentiates between built-in commands and transient commands, and executes the __ 
commands accordingly. 

This section describes the responsibilities and capabihties of the CCP in some 
detail. The section begins with a description of the CCP's activities when it first " 
receives control from the Cold Start procedure. The section continues with a general 
discussion of buili-in commands, and concludes with a step-by-step description of 
the procedure the CCP follows to execute the user's commands. — 

When the CCP gains control following a cold start procedure, it displays the 
system prompt at the console. This signifies that the CCP is ready to execute a 
command. The system prompt displays the letter of the drive designated as the initial "~ 
default drive during GENCPM operation. For example, if drive A was specified as 
the initial default drive, the CCP displays the following prompt: 



After displaying the system prompt, the CCP scans the directory of the default drive 
for the file PROFILE.SUB. If the file exists, the CCP creates the command line 
SUBMIT PROFILE; otherwise the CCP reads the user's first command line by mak- 
ing a BDOS Read Console Buffer function call (BDOS Function 10). 

The CCP accepts two different command forms. The simplest CCP command form 
changes the default drive. The following example illustrates a user changing the 
default drive from A to B. 



This command is one of the CCP's built-in commands. Built-in commands are part 
of the CCP. They reside in memory while the CCP is active, and therefore can be 
executed without referencing a disk. 



H DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 



1.6 System Operat 



The second command form the CCP accepts is the standard CP/M command line. 
A standard CP/M command Une consists of a command keyword foHowed by an 
optional command tail. The command keyword and the conmiand tail can be typed 
in any combination of upper-case and lower-case letters; the CCP converts all letters 
in the command Une to upper-case. The following syntax defines the standard CP/M 
command line; 

<command> <command tail> 



where 

<command> 



= > <filespec> or 
<built-in> 

= > (no command tail) or 

<filespec> or <filespec><de!imiter><filespec> 

= > {d:}filename{.typH;password} 

= > one of the CCP built-in commands 

= > one or more blanks or a tab or one of the 

following:" = ,[]<> " 

= > CP/M 3 drive specification, "A "through "P" 

= > 1 to 8 character filename 

= > 1 to 3 character filetype 

= > 1 to 8 character password value 

Fields enclosed in curly brackets are optional. If there is no drive {d:} present in a file 
specification <filespec>, the default drive is assumed. If the type field {.typ} is omit- 
ted, a type field of all blanks is implied. Omitting the password field {^password} 
implies a password of all blanks. When a command line is entered at the console, it 
is terminated by a return or line-feed keystroke. 

Transient programs that run under CP/M 3 are not restricted to the above com- 
mand tail definition. However, the CCP only parses command tails in this format for 
transient programs. Transient programs that define their command tails differently 
must perform their own command tail parsing. 



<command tail> 

<filespec> 
<built-in> 
<delimiter> 

d: 

filename 

typ 

password 



m DIGITAL RESEARCH'" 



1.6 System Opera 



CP/M 3 Programmer's Guide 



The command field must identify either a built-in command, a transient program, 
or a submit file. For example, USER is the keyword that identifies the buih-in com- 
mand that changes the current user number. The CP/M 3 CCP displays the user 
number in the system prompt when the user number is non-zero. The following 
example illustrates changing the user number from zero to 15. 



e>USER 15 
15B> 



The following table summarizes the built-in commands. 





Table 1-1. CP/M 3 Built-in Commands 


Command 


Meaning 


DIR 


displays a list of all filenames from a disk directory except those 
marked with the SYS attribute. 


DIRSYS 


displays a filename list of those files marked with the SYS 
attribute in the directory. 


ERASE 


erases a filename from a disk directory and releases the storage 
occupied by the file. 


RENAME 


renames a file. 


TYPE 


displays the contents of an ASCII character file at your console 
output device. 


USER 


changes from one user number to another. 



Some built-in commands have associated command files which expand upon the 
options provided by the built-in command. If the CCP reads a command line and 
discovers the built-in command does not support the options requested in the com- 
mand hne, the CCP loads the built-in function's corresponding command file to 
perform the command. The DIR command is an example of this type of command. 
Simple DIR commands are supported by the DIR built-in directly. More complex 
requests are handled by the DIR.COM utility. 



CP/M 3 Programmer's Guide 1.6 System Operation 

Alt command keywords that do not identify built-in commands identify either a 
tiansient program file or a submit file. If the CCP identifies a command keyword as 
a transient program, the transient program file is loaded into the TPA from disk and 
executed. If it recognizes a submit file, the CCP reconstruas the command line into 

the following form: 

SUBMIT <command> <command tail> 

and attempts to load and execute the SUBMIT utility. Thus, the original command 
field becomes the first command tail field of the SUBMIT command. Section 1.6.5 
describes the execution of CP/M 3's SUBMIT utility. The procedure the CCP follows 
to parse a standard command line and execute built-in and transient commands is 
described as follows: 

1. The CCP parses the command fine to pick up the command field, 

2. If the command field is not preceded by a drive specification, or followed by 
a filetype or password field, the CCP checks to see if the command is a CCP 
built-in function. If the command is a built-in command, and the CCP can 
support the options specified in the command tail, the CCP executes the 
command. Otherwise, the CCP goes on to step 3. 

3. At this point the CCP assumes the command field references a command file 
or submit file on disk. If the optional filetype field is omitted from the com- 
mand, the CCP usually assumes the command field references a file of type 
COM, For example, if the command field is PIP, the CCP attempts to open 
die file PIP.COM. 

Optionally, the CP/M 3 utility SETDEF can specify that a filetype of SUB 
also be considered when the command filetype field is omitted. When this 
automatic submit option is in effect, the CCP attempts to open the command 
with a filetype of COM. If the COM file cannot be found, the CCP repeats 
the open operation with a filetype of SUB. As an alternative, the order of 
open operations can be reversed so that the CCP attempts to open with a 
filetype of SUB first. In either case, the file that is found on disk first deter- 
mines the filetype field that is ultimately associated with the command. 
If the filetype field is present in the command, it must equal COM, SUB or 
PRL. A PRL file Is a Page Relocatable file used in Digital Research's multi- 
user operating system, MP/M". Under CP/M 3, the CCP handles PRL files 
exactly like COM files. 



IS DIGITAL RESEARCH™ 



1.6 System Operation CP/M 3 Programmer's Guide 

1/ the command field is preceded by a drive specification {d:}, the CCP attempts _ 
to open the command or submit file on the specified drive. Otherwise, the 
CCP attempts to open the file on the drives specified in the drive chain. 
The drive chain specifies up to four drives that arc to be referenced in sequence 
for CCP open operations of command and submit files. If an open operation 
is unsuccessful on a drive in the drive chain because the file cannot be found, 
the CCP repeats the open operation on the next drive in the chain. This 
sequence of open operations is repeated until the file is found, or the drive — 
chain is exhausted. The drive chain contains the current default drive as its 
only drive unless the user modifies the drive chain with the CP/M 3 SETDEF 
utility. _ 

When the current user number is non-zero, all open requests that fail because 

the file cannot be found, attempt to locate the command file under user zero. 

If the file exists under user zero with the system attribute set, the file is _ 

opened from user zero. This search for a file under user zero is made by the 

BDOS Open File funaion. Thus, the user zero open attempt is made before 

advancing to the next drive in the search chain. 

When automatic submit is in effect, the CCP attempts to open with the first 

filetype, SUB or COM, on all drives in the search chain before trying the 

second filetype. 

In the banked system, if a password specified in the command field does not 

match the password of a file on a disk protected in Read mode, the CCP file 

open operation is terminated with a password error. 

If the CCP does not find the command or submit file, it echoes the command 

line followed by a question mark to the console. If it finds a command file 

with a filetype of COM or PRL, the CCP proceeds to step 4. If it finds a 

submit file, it reconstruas the command Une as described above, and repeats "~ 

step 3 for the command, SUBMIT.COM. 



■ DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 1.6 System Operation 

4. When the CCP successfully opens the command file, it initializes the follow- 
ing Page Zero fields for access by the loaded transient program: 

0050H : Drive that the command file was loaded from 
005 IH : Password address of first file in command tail 
0053H : Password length of first file in command tail 
0054H : Password address of second file in command tail 
0056H : Password length of second file in command tail 
005CH : Parsed FCB for first file in command tail 
006CH : Parsed FCB for second file in command tail 
0080H : Command tail preceded by command tail length 
Page Zero initialization is covered in more detail in Section 2.4. 

5. At this point, the CCP calls the LOADER module to load the command file 
into the TPA. The LOADER module terminates the load operation if a read 
etror occurs, or if the available TPA space is not large enough to contain the 
file. If no RSXs are resident in memory, the available TPA space is deter- 
mined by the address LOADER_base because the LOADER cannot load over 
itself. Otherwise, the maximum TPA address is determined by the base address 
of the lowest RSX in memory. 

6. Once the program is loaded, the LOADER module checks for a RSX header 
on the program. Programs with RSX headers are identified by a return 
instruction at location lOOH. 

If an RSX header is present, the LOADER relocates all RSXs attached to the 
end of the program, to the top of the TPA region of memory under the 
LOADER module, or any other RSXs that are already resident. It also updates 
the address in location 0006H of Page Zero to address the lowest RSX in 
memory. Finally, the LOADER discards the RSX header and relocates the 
program file down one page in memory so that the first executable instruc- 
tion resides at lOOH. 

7. After initializing Page Zero, the LOADER module sets up a 32-byte stack 
with the return address set to location OOOOH of Page Zero and jumps to 
location lOOH. At this point, the loaded transient program begins execution. 



n » 



DIGITAL RESEARCH'" 



1.6 System Operation CP/M 3 Programmer's Guide " 

When a transient program terminates execution, the BIOS warm start routine 
reloads the CCP into memory. When the CCP receives control, it tests to see if RSXs 
are resident in memory. If not, it relocates the LOADER module below the BDOS 
module at the top of the TPA region of memory. Otherwise, it skips this step because 
the LOADER module is already resident. The CCP execution cycle then repeats. " 

Unlike earlier versions of CP/M, the CCP does not reset the disk system at warm 
start. However, the CCP does reset the disk system if a CTRL-C is typed at the _ 
prompt. 

1.6.3 Transient Program Operation 

A transient program is one that the CCP loads into the TPA region of memory 
and executes. As the name transient implies, transient programs are not system resi- 
dent. The CCP must load a transient program into memory every time the program 
is to be executed. For example, the utilities PIP and RMAC" that are shipped with 
CP/M 3 execute as transient programs; programs such as word processing and 
accounting packages distributed by applications vendors also execute as transient 
programs under CP/M 3, ~ 

Section L6.2 describes how the CCP prepared the CP/M 3 environment for the 
execution of a transient program. To summarize, the CCP initiaHzes Page Zero to _ 
contain parsed command-line fields and sets up a 32-byte stack before jumping to 
location OlOOH to pass control to the transient program. In addition, the CCP might 
also load RSXs attached to the command file into memory for access by the transient 
program. *" 

Generally, an executing transient program communicates with the operating sys- 
tem only throu^ BDOS function calls. Transient programs make BDOS function — 
calls by loading the CPU registers with the appropriate entry parameters and calling 
location 0005H in Page Zero. 

Transient programs can use BDOS Function 50, Call BIOS, to access BIOS entry 
points. This is the preferred method for accessing the BIOS; however, for compatibil- 
ity with earlier releases of CP/M, transient programs can also make direa BIOS calls 
for console and list I/O by using the jump instruction at location OOOOH in Page "" 
Zero. But, to simplify portability, use direct BIOS calls only where the primitive level 
of functionality provided by the BIOS functions is absolutely required. For example, 
a disk formatting program must bypass CP/M's disk organization to do its job, and ^ 
therefore is justified in making direa BIOS calls. Note however, that disk formatting 
programs are rarely portable. 



ii DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 1.6 System Operation 

A transient program can terminate execution in one of three ways: by jumping to 
location OOOOH, by making a BDOS System Reset call, or by making a BDOS Chain 
To Program call. The first two methods are equivalent; they pass control to the BIOS 
warm start entry point, which then loads the CCP into the TPA, and the CCP 
prompts for the next command. 

The Chain to Program call allows a transient program to specify the next com- 
mand to be executed before it terminates its own execution. A Program Chain call 
executes a standard warm boot sequence, but passes the command specified by the 
terminating program to the CCP in such a way that the CCP executes the specified 
command instead of prompting the console for the next command. 

Transient programs can also set a Program Return Code before terminating by 
making a BDOS Function 108 call, Get/Set Program Return Code, The CCP initial- 
izes the Program Return Code to zero, successful, when it loads a transient program, 
unless the program is loaded as the result of a program chain. Therefore, a transient 
program that terminates successfully can use the Program Return Code to pass a 
value to a chained program. If the program terminates as the result of a BDOS fatal 
error, or a CTRL-C entered at the console, the BDOS sets the return code to an 
unsuccessful value. All other types of program termination leave the return code at 
its current value. 

The CCP has a conditional command facility that uses the Program Return Code. 
If a command line submitted to the CCP by the SUBMIT utility begins with a colon, 
the CCP skips execution of the command if the previous command set an unsuccess- 
ful Program Return Code. In the following example, the SUBMIT utility sends a 
command sequence to the CCP: 

A>SUBmT SUBFILE 

A>COMPUTE RESULTS, DAT 
A > : REPORT RESUL TS.DfiT 

The CCP does not execute the REPORT command if the COMPUTE command sets 
an unsuccessful Program Return Code. 

1.6.4 Resident System Extension Operation 

This section gives a general overview of RSX use, then describes how RSXs are 
loaded, defines the RSX file structure, and tells how the LOADER module uses the 
RSX prefix and flags to manage RSX activity. 



S DIGITAL RESEARCH™ 



1.6 System Operation CP/M 3 Programmer's Guide 



A Resident System Extension (RSX) is a special type of program that can be 
attached to the operating system to modify or extend the functionality of the BDOS. 
RSX modules intercept BDOS functions and either perform them, translate them into 
other BDOS functions, or pass them through untouched. The BDOS executes non- 
inteccepted functions in the standard manner. 

A transient program can also use BDOS Function 60, Call Resident System Exten- 
sion, to call an RSX for special functions. Function 60 is a general purpose function 
that allows customized interfaces between programs and RSXs. 

Two examples of RSX applications are the GET utility and the LOADER module. 
The GET.COM command file has an attached RSX, GET.RSX, which intercepts all 
console input calls and returns characters from the file specified in the GET command 
line. The LOADER module is another example of an RSX, but it is special because 
it supports Function 59, Load Overlay. It is always resident in memory when other 
RSXs are active. 

RSXs are loaded into memory at program load time. As described in Section 1.6.2, 
after the CCP locates a command file, it calls the LOADER module to load the 
program into the TPA. The LOADER loads the transient program into memory 
along with any attached RSXs. Subsequently, the loader relocates each attached RSX 
to the top of the TPA and adjusts the TPA size by changing the jump at location 
0005H in Page Zero to point to the RSX. When RSX modules reside in memory, the 
LOADER module resides directly below the BDOS, and the RSX modules stack 
downward from it. 

The order in which the RSX modules are stacked affects the order in which they 
intercept BDOS calls. A more recently stacked RSX has precedence over an older 
RSX. Thus, if two RSXs in memory intercept the same BDOS function, the more 
recently loaded RSX handles the function. 

The CP/M 3 utility GENCOM attaches RSX modules to program files. Program 
files with attached RSXs have a special one page header that the LOADER recognizes 
when it loads the command file. GENCOM can also anach one or more RSXs to a 
null command file so that the CCP can load RSXs without having to execute a 
transient program. In this case, the command file consists of the RSX header fol- 
lowed by the RSXs. 

RSX modules are Page Relocatable, PRL, files with the file type RSX. RSX files 
must be page relocatable because their execution address is determined dynamically 
by the LOADER module at load time. RSX files have the following format: 

m DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 



1.6 System Operation 



END OF FILE: 



PRL BIT MAP 



256 BYTE PRL HEADER 



F^ure 1-8. RSX FUe Format 



RSX files begin with a one page PRL header that specifies the total size of the RSX 
prefix and code seaions. The PRL bit map is a string of bits identifying those bytes 
in the RSX prefix and code sections that require relocation. The PRL format is 
described in detail in Appendix B. Note that the PRL header and bit map are removed 
when an RSX is loaded into memory. They are only used by the LOADER module 
to load the RSX. 



The RSX prefix is a standard data struaure that the LOADER module uses to 
manage RSXs [see Section 4.4). Included in this data structure are jump instructions 
to the previous and next RSX in memory, and two flags. The LOADER module 
initializes and updates these jump instructions to maintain the link from location 6 
of Page Zero to the BDOS entry point. The RSX flags are the Remove flag and the 
Nonbanked flag. The Remove flag controls RSX removal from memory. The CCP 
tests this flag to determine whether or not it should remove the RSX from memory 
at system warm start. The nonbanked flag identifies RSXs that are loaded only in 
nonbanked CP/M 3 systems. For example, the CP/M 3 RSX, DIRLBL.RSX, is a 
nonbanked RSX. It provides BDOS Function 100, Set Directory Label, support for 
nonbanked systems only. Banked systems support this function in the BDOS. 

The RSX code section contains the main body of the RSX. This section always 
begins with code to intercept the BDOS function that is supported by the RSX. 
Nonintercepted functions are passed to the next RSX in memory. This seaion can 
also include initialization and termination code that transient programs can call with 
BDOS Function 60. 



IS DIGITAL RESEARCH™ 



1.6 System Operation CP/M 3 Programmer's Guide — 

When the CCP gains control after a system warm start, ii removes any RSXs in 
memory that have the Remove flag set to OFFH. All other RSXs remain active in ~* 
memory. Setting an RSX's Remove flag to OFFH indicates that the RSX is not active 
and it can be removed. Note that if an RSX marked for removal is not the lowest active 
RSX in memory, it still occupies memory after removal. Although the removed RSX — 
cannot be executed, its space is returned to the TPA only when all the lower RSXs are 
removed. 

There is one special case where the CCP does not remove an RSX with the Remove ~ 
flag set to OFFH following warm start. This case occurs on warm starts following the 
load of an empty file with attached RSXs. This exception allows an RSX with the 
Remove flag set to be loaded into memory before a transient program. The transient ■" 
program can then access the RSX during execution. After the transient program 
, however, the CCP removes the RSX from the system environment. 



As an example of RSX operation, here is a description of the operation of the GET 
utility. The GET.COM command file has an attached RSX. The LOADER moves 
this RSX to the top of the TPA when it loads the GET.COM command file. The 
GET utility performs necessary initializations which include opening the ASCII file 
specified in the GET command line. It also makes a BDOS Function 60 call to 
initialize the GET.RSX. At this point, the GET utility terminates. Subsequently, the 
GET.RSX intercepts all console input calls and returns characters from the file speci- 
fied in the GET command Hiie. It continues this action until it reads end-of-file. At 
this point, it sets its Remove flag in the RSX prefix, and stops intercepting console 
input. On the following warm boot, the CCP removes the RSX from memory. 

1.6.5 SUBMIT Operation 

A SUBMIT command line has the following syntax: 

SUEMFT <filespec> <parameters> 

If the CCP identifies a command as a submit file, it automatically inserts the SUBMIT 
keyword into the command liae as described in Section 1.6.2. 



S DIGITAL RESEARCH- 



^ CP/M 3 Programmer's Guide 1.6 System Operation 

When the SUBMIT utility begins execution, it opens and reads the file specified by 
<filespec> and creates a temporary submit file of type $S$ on the system's tempo- 
rary file drive. GENCPM initializes the temporary file drive to the CCP's current 
default drive. The SETDEF utility can set the temporary file drive to a specific drive. 
As it creates the temjxjrary file, SUBMIT performs the parameter substiturions requested 
by the <parameters> subfield of the SUBMIT command line. See the CP/M Plus 
(CP/M Version 3} Operating System User's Guide for a detailed description of this 
process. 

After SUBMIT creates the temporary submit file, its operation is similar to that of 
the GET utility described in Seaion 1.6.4. The SUBMIT command file also has an 
anached RSX that performs console input redirection from a file. However, the 
SUBMIT RSX expands upon the simpler facilities provided by the GET RSX, Com- 
mand lines in a submit file can be marked to indicate whether they are program or 
CCP input. Furthermore, if a program exhausts all its program input, the next SUB- 
MIT command is a CCP command, the SUBMIT RSX temporarily reverts to console 
input. Redirected input from the submit file resumes when the program terminates. 

Because CP/M 3's submit facility is implemented with RSXs, submit files can be 
nested. That is, a submit file can contain additional SUBMIT or GET commands. 
Similarly, a GET command can specify a file that contains GET or SUBMIT com- 
mands. For example, when a SUBMIT command is encountered in a submit file, a 
new SUBMIT RSX is created below the current RSX. The new RSX handles console 
input until it reads end-of-fiie on its temporary submit file. At this point, control 
reverts to the previous SUBMIT RSX. 



1.7 System Control Block 

The System Control Block, SCB, is a 100 byte CP/M 3 data structure that resides 
in the BDOS system component. The SCB contains internal BDOS flags and data, 
CCP flags and data, and other system information such as console characteristics and 
the current date and time. The BDOS, BIOS, CCP system components as well as 
CP/M 3 utilities and RSXs reference SCB fields. BDOS Function 49, Get/Set System 
Control Block, provides access to the SCB fields for transient programs, RSXs, and 
the CCP. 



W DIGITAL RESEARCH™ 



1.7 System Control Block CP/M 3 Progi 

However, use caution when you access the SCB through Function 49 for two 
reasons. First, the SCB is a CP/M 3 data structure. Digital Research's multi-user 
operating system, MP/M, does not support BDOS Function 49. Programs that access 
the SCB can run only on CP/M 3. Secondly, the SCB contains critical system param- 
eters that reflect the current state of the operating system. If a program modifies these 
parameters illegally, the operating system might crash. However, for apphcation writ- 
ers who are writing system-oriented applications, access to the SCB variables might 
ptove valuable. 

For example, the CCP default drive and current user number are maintained in the 
System Control Block. This information is displayed in the system prompt. If a 
transient program changes the current disk or user number by making an explicit 
BDOS call, the System Control Block values are not changed. They continue to reflect 
the state of the system when the transient program was loaded. For compatibihty 
with CP/M Version 2, the current disk and user number are also maintained in 
location 0004H of Page Zero. The high-order nibble contains the user number, and 
the low-order nibble contains the drive. 

Refer to the description of BDOS Function 49 in Section 2.5 for more information 
on the System Control Block. The SCB fields are also discussed in Appendix A. 



End of Section 1 



i DIGITAL RESEARCH'" 



Section 2 
The BDOS System Interface 



This section describes the operating system services available to a transient pro- 
gram through the BDOS module of CP/M 3. The section begins by defining how a 
transient program calls BDOS functions, then discusses serial I/O for console, list and 
auxiliary devices, the file system, and Page Zero initialization. 



2.1 BDOS Calling Conventions 

CP/M 3 uses a standard convention for BDOS function calls. On entry to the 
BDOS, register C contains the BDOS function number, and register pair DE contains 
a byte or word value or an information address. BDOS functions return single-byte 
values in register A, and double-byte values in register pair HL, In addition, they 
return with register A equal to L, and register H equal to B. If a transient program 
makes a BDOS call to a nonsupported function number in the range of to 127, the 
BDOS returns with register pair HL set to OFFFFH. For compatibility with MP/M, 
the BDOS returns with register pair HL set to OOOOH on nonsupported function 
numbers in the range of 128 to 255. Note that CP/M 2 returns with HL set to zero 
on all invalid function calls. CP/M 3's register passing conventions for BDOS func- 
tion calls are consistent with the conventions used by the Intel PL/M systems pro- 
gramming language. 

When a transient program makes a BDOS function call, the BDOS does not restore 
registers to their entry values before returning to the calling program. The responsi- 
bility for saving and restoring any critical register values rests with the calling program. 

When the CCP loads a transient program, the LOADER module sets the stack 
pointer to a 16 level stack, and then pushes the address OOOOH onto the stack. Thus, 
an immediate return to the system is equivalent to a jump to OOOOH. However, most 
transient programs set up their own stack, and terminate execution by making a 
BDOS System Reset call (Function 0) or by jumping to location OOOOH. 



BDiCJITAL REStARCH" 



conin 


e^u 


1 


' 


ors 


lOOh 


nextc: 


MUi 


fCOl 




call 


bdos 
'* ' 




jnz 


nsKt 



2.1 BDOS Calling Conventions CP/M 3 Programmer's Guide "■ 

The following example illustrates how a transient program calls a BDOS function. _ 
This program reads characters continuously until it encounters an asterisk. Then it 
terminates execution by returning to the system. 

bdos eiu 0005 h iBDDS enlr/ point in PaSe Zero "" 

jBDDS console input function 

iBase of Transient Proaraw Area _ 

iReturn characte r in A 

lEnd of processinS? 

iLoop if not , 

!Te rtiiinale pros ram > 



2.2 BDOS Serial Device yO 

Under CP/M 3, serial device I/O is simply input to and output from simple devices 
such as consoles, line printers, and communications devices. These physical devices 
can be assigned the logical device names defined below: 

CONIN: logical console input device 

CONOUT: logical console output device 

AUXIN: logical auxiliary input device 

AUXOUT: logical auxiliary output device 

LST: logical list output device 

If your system suppons the BIOS DEVTBL funaion, the CP/M 3 DEVICE utility 
can display and change the assignment of logical devices to physical devices. DEVICE 
can also display the names and attributes of physical devices supported on your 
system. If your system does not support the DEVTBL entry point, then the logical to 
physical device assignments are fixed by the BIOS. 

In general, BDOS serial I/O functions read and write an individual ASCII charac- 
ter, or charaaer string to and from these devices, or test the device's ready status. 
For these BDOS functions, a string of characters is defined as zero to N characters 
terminated by a delimiter. A block of characters is defined as zero to N characters 
where N is specified by a word count field. The maximum value of N in both cases 
is limited only by available memory. The following list summarizes BDOS serial 
device I/O functions. 



CP/M 3 Programmer's Guide 2.2 BDOS Serial Device I/O 

Read a character from CONIN: 

Read a character buffer from CONIN: 

Write a character to CONOUT: 

Write a string of charaaers to CONOUT: 

Write a block of characters to CONOUT: 

Read a character from AUXIN: 

Write a character to AUXOUT: 

Write a character to LST: 

Write a block of characters to LST: 

Interrogate CONIN:, AUXIN;, AUXOUT: ready 

CP/M 3 cannot run unless CONIN: and CONOUT; are assigned to a physical 
console. The remaining logical devices can remain unassigned. If a logical output 
device is not as:«igned to a physical device, an output BDOS call to the logical device 
performs no action. If a logical input device is not assigned to a physical device, an 
input BDOS call to the logical device typically returns a CTRL-Z {lAH), which 
indicates end-of-file. Note that these aaions depend on your system's BIOS 
implementation. 

2.2.1 BDOS Console I/O 

Because a transient program's main interaction with its user is through the console, 
the BDOS supports many console I/O functions, Console I/O functions can be divided 
into four categories: basic console I/O, diren console I/O, buffered console input, 
and special console functions. Using the basic console I/O functions, programs can 
access the console device for simple input and output. The basic console I/O func- 
tions are: 

1. Console Input - Inputs a single character 

2. Console Output- Outputs a single character 

9. Print String - Outputs a string of charaaers 
11. Console Status - Signals if a charaaer is ready for input 
111. Print Block - Outputs a block of characters 

The input function echoes the character to the console so that the user can identify 
the typed character. The output functions expand tabs in columns of ei^t characters. 



m DIGITAL RESEARCH" 



2.2 BDOS Serial Device I/O CP/M 3 Programmer's Guide 

The basic I/O functions also monitor the console to stop and start console output 
scroll at the user's request. To provide this support, the console output functions 
make internal status checks for an input character before writing a character to the 
output device. The console input and console status funaions also check the input 
character. If the user types a CTRL-S, these functions make an additional BIOS 
console input call. This input call suspends execution until a character is typed. If the 
typed character is not a CTRL-Q, an additional BIOS console input call is made. 
Execution and console scrolling resume when the user types a CTRL-Q. 

When the BDOS is suspended because of a typed CTRL-S, it scans input for three 
special characters: CTRL-Q, CTRL-C, and CTRL-P. If the user types any other 
character, the BDOS echoes a bell character, CTRL-G, to the console, discards the 
input character, and continues the scan. If the user types a CTRL-C, the BDOS 
executes a warm start which terminates the caUing program. If the user types a 
CTRL-P, the BDOS toggles the printer echo switch. The printer echo switch controls 
whether console output is automatically echoed to the list device, LST:. The BDOS 
signals when it turns on printer echo by sending a bell character to the console. 

All basic console I/O functions discard any CTRL-Q or CTRL-P character that is 
not preceded by a CTRL-S character. Thus, BDOS function 1 cannot read a CTRL- 
S, CTRL-Q, or CTRL-P character. Furthermore, these characters are invisible to the 
console status function. 

The second category of console I/O is direct console I/O. BDOS function 6 can 
provide direct console I/O in situations where unadorned console I/O is required. 
Function 6 actually consists of several sub-functions that support direa console input, 
output, and status checks. The BDOS does not filter out special charaaers during 
direct console I/O. The direct output sub-function does not expand tabs, and the 
direct input sub-function does not echo typed characters to the console. 

The third category of console I/O accepts edited input from the console. The only 
function in this category, Function 10, Read Buffer Input, reads an input line from a 
buffer and recognizes certain control characters that edit the input. As an option, the 
line to be edited can be initialized by the calling program. 

In the nonbanked version of CP/M 3, editing within the buffer is restricted to the 
last character on the line. That is, to edit a charaaer embedded in the line, the user 
must delete all characters that follow the erroneous character, correct the error, and 
then retype the remainder of the line. The banked version of CP/M 3 supports 
complete Hne editing in which characters can be deleted and inserted anywhere in the 
Une. In addition, the banked version can also recall the previously entered line. 

II DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 2.2 BDOS Serial Device I/O 

Funcrion 10 also filters input for certain control charaaers. If the user types a 
CTRL-C as the first character in the line. Function 10 terminates the calHng program 
by branching to the BIOS warm start entry point. A CTRL-C in any other position 
is simply echoed at the console. Function 10 also watches for a CTRL-P keystroke, 
and if it finds one at any position in the command line, it toggles the printer echo 
switch. Function 10 does not filter CTRL-S and CTRL-Q characters, but accepts 
them as normal input. In general, all control characters that Function 10 does not 
recognize as editing control characters, it accepts as input charaaers, Funaion 10 
identifies a control character with a leading caret, *, when it echoes the control 
character to the console. Thus, CTRL-C appears as *C in a Function 10 command 
tine on the screen. 

The final category of console I/O functions includes special functions that modify 
the behavior of other console functions. These functions are: 

109. Get/Set Console Mode 

110. Gel/Set Output Delimiter 

Function 110 can get or set the current delimiter for Function 9, Print String. The 
delimiter is $, when a transient program begins execution. Function 109 gets or sets 
a 16-bit system variable called the Console Mode. The following list describes the 
bits of the Console Mode variable and their functions; 

bit ; If this hit is set. Function 1 1 returns true only if a CTRL-C is typed at the 
console. Programs that make repeated console status calls to test if execution 
should be interrupted, can set this bit to interrupt on CTRL-C only. The 
CCP DIR and TYPE built-in commands run in this mode. 

bit 1 : Setting this bit disables stop and start scroll support for the basic console 
I/O functions, which comprise the first category of functions described in 
this seaion. When this bit is set, Function 1 reads CTRL-S, CTRL-Q, and 
CTRL-P, and Function 1 1 returns true if the user types these characters. Use 
this mode in situations where raw console input and edited output is needed. 
While in this mode, you can use Function 6 for input and input status, and 
Functions 1, 9, and 111 for output without the possibility of the output 
functions intercepting input CTRL-S, CTRL-Q, or CTRL-P characters. 

bit 2 : Setting this bit disables tab expansion and printer echo support for Functions 
2, 9, and 111. Use this mode when non-edited output is required. 



IB DIGITAL RESEARCH™ 



2.2 BDOS Serial Device I/O CP/M 3 Programmer's Guide 

bit 3 : This bit disables all CTRL-C intercept action in the BDOS. This mode is 
usehil for programs that must control their own termination. 

bits 8 and 9 : The BDOS does not use these bits, but reserves them for the CP/M 3 
GET RSX that performs console input redirection from a file. With one 
exception, these bits determine how the GET RSX responds to a program 
console status request (Function 6, Function 11, or direct BIOS). 

bit 8 = 0, bit 9 = - conditional status 

bit 8 = 0, bit 9 = 1 - false status 

bit 8 = 1, bit 9 = - true status 

bit 8 = 1, bit 9 = 1 ■ do not perform redirection 

In conditional status mode, GET responds false to all status requests except for a 
status call preceded immediately by another status call. On the second call, GET 
responds with a true result. Thus, a program that spins on status to wait for a 
character is signaled that a character is ready on the second call. In addition, a 
program that makes status calls periodically to see if the user wants to stop is not 
signaled. 



When a transient program begins execution, the Console Mode bits are normally 
set to zero. However, the CP/M 3 utility GENCOM can attach an RSX header to a 
COM file so that when it is loaded, the console mode bits are set differently. This 
feature allows you to modify a program's console I/O behavior without having to 
change the program. 

2.2.2 Other Serial I/O 

The BDOS supports single character output functions for the logical devices LST: 
and AUXOUT:, an input function for AUXIN:, and status functions for AUXIN: 
and AUXOUT:. A block output function is also supported for the LST: device. 
Unlike the console I/O functions, the BDOS does not intercept control characters or 
expand tabs for these functions. Note that AUXIN: and AUXOUT: replace the 
READER and PUNCH devices supported by earlier versions of CP/M. 



IS DIGITAL RESEARCH" 



"7 CP/M 3 Programmer's Guide 2.3 BDOS File System 

„ 2.3 BDOS FUe System 

' Transient programs depend on the BDOS file system to create, update, and main- 

tain disk files. This section describes the capabilities of the BDOS file system in detail. 
n You must understand the general features of CP/M 3 described in Seaion 1 before 
I t you can use the detail presented in this section. 

nThe remaining introductory paragraphs define the four categories of BDOS file 
functions. This is followed by a review of file naming conventions and disk and file 
organization. The section then describes the data structure used by the BDOS file, 
and directory oriented functions: the File Control Block (FCB). Subsequent Jiscus- 

nsions cover file attributes, user numbers, directory labels and extended File Control 
Blocks (XFCBs), passwords, date and time stamping, blocking and deblocking, multi- 
sector I/O, disk reset and removable media, byte counts, and error handling. These 
n topics are closely related to the BDOS file system. You must be familiar with the 
contents of Section 2 before attempting to use the BDOS functions described individ- 
ually in Section 3. 

I j The BDOS file system supports four categories of functions: file access functions, 

directory functions, drive related functions, and miscellaneous functions. The file 
access category includes functions to create a file, open an existing file, and close a 

nfile. Both the make and open funaions activate the file for subsequent access by 
BDOS file access functions. The BDOS read and write funaions are file access func- 
tions that operate either sequentially or randomly by record position. They transfer 
ndata in units of 128 bytes, which is the basic record size of the file system. The dose 
function makes any necessary updates to the directory to permanently record the 
status of an activated file. 



S DIGITAL RESEARCH" 



2.3 BDOS File System CP/M 3 Programmer's Guide 

BDOS directory funaions operate on existing file entries in a drive's directory. 
This category includes functions to search for one or more files, delete one or more 
files, truncate a file, rename a file, set file anributes, assign a password to a file, and 
compute the size of a file. The search and delete functions are the only BDOS func- 
tions that suppon ambiguous file references. All other direaory and file related func- 
tions require a specific file reference. 

The BDOS drive-related category includes funaions that selea the default drive, 
compute a drive's free space, interrogate drive status, and assign a directory label to 
a drive. A drive's direaory label controls whether or not CP/M 3 enforces file pass- 
word protection, or stamps files with the date and time. Note that the nonbanked 
version of CP/M 3 does not support file passwords. 



The miscellaneous category includes functions to set the current DMA address, 
access and update the current user number, chain to a new program, and flush 
internal blocking/deblocking buffers. Also included are functions that set the BDOS 
multi-sector count, and the BDOS error mode. The BDOS multi-sector count deter- 
mines the number of 128-byte records to be processed by BDOS read and write 
functions. It can range from 1 to 128. The BDOS error mode determines how the 
BDOS file system handles certain classes of errors. 



Also included in the miscellaneous category are hanctions that call the BIOS directly, 
set a program return code, and parse filenames. If the LOADER RSX is resident in 
memory, programs can also make a BDOS funaion call to load an overlay. Another 
miscellaneous function accesses system variables in the System Control Block. 



- O DIGITAL RESEARCH™ 



7[ CP/M 3 Programmer's Guide 2.3 BDOS File System 

The following list summarizes the operations performed by the BDOS file system: 

' I Disk System Reset 

Drive Selection 
•^ File Creation 

; 1 File Open 

File Close 
^^ Direaory Search 

' I File Delete 

' File Rename 

Random or Sequential Read 

Random or Sequential Write 

Interrogate Selected Disks 

Set DMA Address 

Set/Reset File Attributes 

Reset Drive 

Set BDOS Multi-Seaor Count 

Set BDOS Error Mode 

Get Disk Free Space 

Chain to Program 

Flush Buffers 

Get/Set System Control Block 

Call BIOS 

Load Overlay 

Call RSX 

Truncate File 

Set Directory Label 

Get File's Date Stamps and Password Mode 

Write File XFCB 

Set/Get Date and Time 

Set Default Password 

Return CP/M 3 Serial Number 

Get/Set Program Return Code 

Parse Filename 

2.3.1 File Naming Conventions 

Under CP/M 3, a file specification consists of four parts: the drive specifier, the 
filename field, the filetype field, and the file password field. The genera) format for a 
command line file specification is shown below: 

{d:}filename{. typH ;password} 

IflOrCITAL RESEARCH'" 



2.3 BDOS File System 



CP/M 3 Programmer's Guide 



The drive specifier field specifies the drive where the file is located. The filename and 
type fields identify the file. The password field specifies the password if a file is 
password protected. 

The drive, type, and password fields are optional, and the delimiters :.; are required 
only when specifying their associated field. The drive specifier can be assigned a letter 
from A to P where the actual drive letters supponed on a given system are deter- 
mined by the BIOS implementation. When the drive letter is not specified, the c 
default drive is assumed. 



The filename and password fields can contain one to eight non-delimiter charac- 
ters. The filetype field can contain one to three non-delimiter characters. All three 

fields are padded with blanks, if necessary. Omitting the optional type or password 
fields implies a field specification of all blanks. 

The CCP calls BDOS Function 152, Parse Filename, to parse file specifications 
from a command line. Function 152 recognizes certain ASCII characters as valid 
delimiters when it parses a file from a command line. The valid delimiters are shown 
in Table 2-1. 



Table 2-1. 


Valid Filename Delimiters 


ASCII 


1 HEX 


EQUIVALENT 


null 




00 


space 




20 


return 




OD 


lab 




09 
3A 
2E 
3B 


[ 

1 




3D 
2C 
SB 
5D 


< 




3C 


> 

1 




3E 

7C 



H DIGITAL RESEARCH™ 



^ CP/M 3 Programmer's Guide 2.3 BDOS File System 

Function 152 also excludes all control charaaers from the file fields, and translates all 
lower-case letters to upper-case. 

Avoid using parentheses and the backslash character, \, in the filename and filetype 

•-. fields because they are commonly used delimiters. Use asterisk and question mark 

j I characters, * and ?, only to make an ambiguous file reference. When Funrtion 152 

encounters an * in a filename or filetype field, it pads the remainder of the field with 

question marks. For example, a filename of X*.* is parsed to X???????.???, The 

I I BDOS search and delete functions treat a ? in the filename and type fields as follows: 

' ' A ? in any position matches the corresponding field of any directory entry belonging 

to the current user number. Thus, a search operation for X????.'??.??? finds all the 

^ current user files on the directory beginning in X, Most other file related BDOS 

I I functions treat the presence of a ? in the filename or type field as an error. 

_ It is not mandatory to follow the file naming conventions of CP/M 3 when you 

I I create or rename a file with BDOS funaions. However, the conventions must be used 

if the file is to be accessed from a command line. For example, the CCP cannot locate 

a command file in the directory if its filename or type field contains a lower-case 

rj letter. 

As a general rule, the filetype field names the generic category of a particular file, 
"^ while the filename distinguishes individual files in each category. Although ihey are 
I j generally arbitrary, the following list of filetypes names some of the generic categories 
that have been established. 

n ASM Assembler Source PU PL/I Source File 

' PRN Printer Listing REL Relocatable Module 

HEX Hex Machine Code TEX TEX Formatter Source 

"I BAS Basic Source File BAK ED Source Backup 

! \ IKT Intermediate File SYM SID Symbol File 

COM Command File S$S Temporary File 

^ PRL Page Relocatable DAT Data File 

I 1 SPR Sys. Page Reloc. SYS System File 

2.3.2 Disk and File Organization 

1 The BDOS file system can support from one to sixteen logical drives. The maxi- 

mum file size supported on a drive is 32 megabytes. The maximum capacity of a 
^ drive is determined by the data block size specified for the drive in the BIOS. The 
data block size is the basic unit in which die BDOS allocates disk space to files. 



UDlCiTAL RESEARCH- - 



2.3 BDOS File System CP/M 3 Programmer's Guide 

Table 2-2 displays the relationship between data block size and drive capacity. 
Table 2-2. Logical Drive Capacity 



Data Block Size 


1 Maximum Drive Capacity 


IK 


256 Kilobytes 


2K 


64 Megabytes 


4K 


128 Megabytes 


8K 


256 Megabytes 


16K 


512 Megabytes 



Logical drives are divided into two regions: a directory area and a data area. The 
directory area contains from one to sixteen blocks located at the beginning of the 
drive. The actual number is set in the BIOS. This area contains entries that define 
which files exist on the drive. The directory entries corresponding to a particular file 
define those data blocks in the drive's data area that belong to the file. These data 
blocks contain the file's records. The directory area is logically subdivided into six- 
teen independent directories identified as user through 15. Each independent direc- 
tory shares the actual directory area on the drive. However, a file's directory entries 
cannot exist under more than one user number. In general, only files belonging to 
the current user number are visible in the directory. 

Each disk file consists of a set of up to 262,144 128-byte records. Each record in 
a file is identified by its position in the file. This position is called the record's random 
record number. If a file is created sequentially, the first record has a position of zero, 
while the last record has a position one less than the number of records in the file. 
Such a file can be read sequentially in record position order beginning at record zero, 
or randomly by record position, Conversely, if a file is created randomly, records are 
added to the file by specified position. A file created in this way is called sparse if 
positions exist within the file where a record has not been written. 

The BDOS automatically allocates data blocks to a file to contain its records on 
the basis of the record positions consumed. Thus, a sparse file that contains two 
records, one at position zero, the other at position 262,143, consumes only two data 
blocks in the data area. Sparse files can only be created and accessed randomly, not 
sequentially. Note that any data block allocated to a file is permanently allocated to 
the file until the file is deleted or truncated. These are the only mechanisms supported 
by the BDOS for releasing data blocks belonging to a file. 



m DIGITAL RESEARCH- 



CP/M 3 Programmer's Guide 2.3 BDOS File System 

Source files under CP/M 3 arc treated as a sequence of ASCII characters, where 
each line of the source file is followed by a carriage return line-feed sequence, ODH 
followed by OAH. Thus a single 128-byte record could contain several lines of source 
text. The end of an ASCII file is denoted by a CTRL-Z character, lAH, or a real end 
of file, returned by the BDOS read operation. CTRL-Z characters embedded within 
machine code files such as COM files are ignored. The actual end-of-file condition 
returned by the BDOS is used to terminate read operations. 

2.3.3 File Control Block Definition 

The File Control Block, FCB, is a data structure that is set up and initialized by a 
transient program, and then used by any BDOS file access and directory functions 
called by the transient program. Thus the FCB is an important channel for informa- 
tion exchange between the BDOS and a transient program. For example, when a 
program opens a file, and subsequently accesses it with BDOS read and write record 
functions, the BDOS file system maintains the current file state and position within 
the program's FCB. Some BDOS functions use certain fields in the FCB for invoking 
special options. Other BDOS functions use the FCB to return data to the calling 
program. In addition, all BDOS random I/O functions specify the random record 
number with a 3-byte field at the end of the FCB. 

When a transient program makes a file access or directory BDOS function call, 
register pair DE must address an FCB. Tlie length of the FCB data area depends on 
the BDOS function. For most functions, the required length is 33 bytes. For random 
I/O functions, the Truncate File function, and the Compute File Size funaion, the 
FCB length must be 36 bytes. The FCB format is shown on the next page. 



n ,,, 



DIGITAL RESEARCH- 



2.3 BDOS File Syste 



CP/M 3 Programmer's Guide 



12 13 14 15 16 



31 32 33 34 35 



where 
dr 



drive code (0 - 16) 

= > use default drive for file 

1 = > auto disk select drive A, 

2 = > auto disk select drive B, 

16 = > auto disk selea drive P. 

contain the filename in ASCII 
upper-case, with high bit = 0. 
fl',..., f8' denote the high- 
order bit of these positions, 
and are file attribute bits. 

contain the filetype in ASCII 

upper-case, with high bit = 0. 

tl', t2', and t3' denote the 

high bit of these positions, 

and are file attribute bits. 

tl' = 1 => Read/Only file 

t2' = 1 = > System file 

t3' = 1 = > File has been archived 

contains the current extent number, 
usually set to by the calling program, 
but can range 0-31 during file I/O 

reserved for internal system use 

reserved for internal system use 

record count for extent "ex" 
takes on values from - 255 
{values greater than 128 imply 
record count equals 128) 



lit. DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 2.3 BDOS File System 

d0...dn filled-in by CP/M 3, reserved for 

system use 

cr current record to read or write in 

a sequential file operation, normally 
set to zero by the calling program 
when a file is opened or created 

r0,rl,r2 optional random record number in the 

range 0-262,143 (0 - 3FFFFH). 
ro,rl,r2 constitute a 18 bit value 
with low byte rO, middle byte rl, and 
hi^ byte r2. 



For BDOS directory funaions, the calling program must initialize bytes through 
11 of the FCB before issuing the function call. The Set Directory Label and Write 
File XFCB functions also require the calling program to initialize byte 12. The Rename 
File function requires the calling program to place the new filename and type in bytes 
17 through 27. 

BDOS open or make function calls require the calling program to intialize bytes 
through 12 of the FCB before making the call. Usually, byte 12 is set to zero. In 
addition, if the file is to be processed from the beginning using sequential read or 
write functions, byte 32, cr, must be zeroed. 

After an FCB is aaivated by an open or make operation, a program does not have 
to modify the FCB to perform sequential read or write operations. In fact, bytes 
through 31 of an activated FCB should not be modified. However, random I/O 
functions require that a program set bytes 33 through 35 to the requested random 
record number prior to making the function call. 

File directory entries maintained in the directory area of each disk have the same 
format as FCBs, excluding bytes 32 through 35, except for byte which contains the 
file's user number. Both the Open File and Make File functions bring these entries, 
excluding byte 0, into memory in the FCB specified by the calling program. All read 
and write operations on a file must specify an FCB activated in this n 



2.3 BDOS File System CP/M 3 Programmer's Guide 

The BDOS updates the memory copy of the FCB during file processing to maintain 
the current position within the file. During file write operations, the BDOS updates 
the memory copy of the FCB to record the allocation of data to the file, and at the 
termination of file processing, the Close File function permanently records this infor- 
mation on disk. Note that data allocated to a file during file write operations is not 
completely recorded in the directory until the catling program issues a Close File call. 
Therefore, a program that creates or modifies files must close the files at the end of 
any write processing. Otherwise, data might be lost. 

The BDOS Search and Delete functions support multiple or ambiguous file refer- 
ences. In general, a question mark in the filename, filetype, or extent field matches 
any value in the corresponding positions of directory FCBs during a directory search 
operation. The BDOS search functions also recognize a question mark in the drive 
code field, and if specified, they return all directory entries on the disk regardless of 
user number, including empty entries. A direaory FCB that begins with E5H is an 
empty directory entry. 

2.3.4 File Attributes 

The high-order bits of the FCB filename, fl',..>f8', and filetype, tl',t2',t3', fields 
are called attribute bits. Attributes bits are 1 bit Boolean fields where 1 indicates on 
or true, and indicates off or false. Attribute bits indicate two kinds of attributes 

within the file system: file attributes and interface attributes. 

The file attribute bits, fr,...,f4' and tr,i2',t3', can indicate that a file has a defined 
file attribute. These bits are recorded in a file's directory FCBs. File attributes can be 
set or reset only by the BDOS Set File Attributes function. When the BDOS Make 
File funaion creates a file, it initializes all file attributes to zero. A program can 
interrogate file attributes in an FCB aaivated by the BDOS Open File function, or in 
directory FCBs returned by the BDOS Search For First and Search For Next functions. 

Note: the BDOS file system ignores file attribute bits when it anempts to locate a file 
in the directory. 

The file system defines the file attribute bits, tr,t2',t3', as follows: 

tl': Read-Only attribute - The file system prevents write operations to a file with 
the read-only attribute set. 



- H DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 



2.3 BDOS File Sysie 



n 
n .■: 

n 



System attribute - This attribute, if set, identifies the iile as a CP/M 3 system 
file. System files are not usually displayed by the CP/M 3 DIR command. In 
addition, user-zero system files can be accessed on a read-only basis from other 
user numbers. 

Archive attribute - This attribute is designed for user written archive programs. 
When an archive program copies a file to backup storage, it sets the archive 
attribute of the copied files. The file system automaiically resets the archive 
attribute of a direaory FCB that has been issued a write command. The archive 
program can test this attribute in each of the file's direaory FCBs via the BDOS 
Search and Search Next funaions. If all directory FCBs have the archive attri- 
bute set, it indicates that the file has not been modified since the previous 
archive. Note that the CP/M 3 PIP utility supports file archival. 

Attributes fl' through f4' are available for definition by the user. 

The interface attributes are indicated by bits f5' through f8' and cannot be used as 
file attributes. Interface attributes f5' and i6' can request options for BDOS Make 
File, Close File, Delete File, and Set File Attributes functions. Table 2-3 defines options 
indicated by the f5' and f6' interface attribute bits for these functions. 



Table 2-3. BDOS Interface Attributes 



BDOS Function \ 


Interface Attribute Definition 


16. Close FUe 


f5' = 1 : Partial Close 


19. Delete File 


f5' = 1 : Delete file XFCBs 
only 


22. Make File 


f6' = 1 : Assign password to 
file 


30. Set File Attributes 


f6' = 1 : Set file byte count 



Section 3 discusses each interface attribute in detail in the definitions of the above 
functions. Attributes f5' and f6' are always reset when control is returned to the 
calling program. Interface attributes f7' and f8' are reserved for internal use by the 
BDOS file system. 



LIS DIGITAL RESEARCH- - 



2.3 BDOS File System CP/M 3 Programmer's Guide — 

2.3.5 User Number Conventions 

The CP/M 3 User facility divides each drive directory into sixteen logically inde- 
pendent direaories, designated as user through user 15. Physically, all user direc- 
tories share the directory area of a drive. In most other aspects, however, they are 
independent. For example, files with the same name can exist on different user num- ~ 
hers of the same drive with no conflict. However, a single file cannot reside under 
more than one user number. 

Only one user number is active for a program at one time, and the current user 
number applies to all drives on the system. Funhermore, the FCB format does not 
contain any field that can be used to override the current user number. As a result, _ 
all file and directory operations reference directories associated with the current user 
number. However, it is possible for a program to access files on different user num- 
bers; this can be accomplished by setting the user number to the file's user number 
with the BDOS Set User function before making the desired BDOS funaion call for ~ 
the file. Note that this technique must be used carefully. An error occurs if a program 
attempts to read or write to a file under a user number different from the user 
number that was active when the file was opened. — 

When the CCP loads and executes a transient program, it initializes the user num- 
ber to the value displayed in the system prompt. If the system prompt does not 
display a user number, user zero is implied. A transient program can change its user 
number by making a BDOS Set User function call. Changing the user number in this 
way does not affect the CCP's user number displayed in the system prompt. When 
the transient program terminates, the CCP's user number is restored. However, an — 
option of the BDOS Program Chain command allows a program to pass its current 
user number and default drive to the chained program. 

User has special properties under CP/M 3. When the current user number is not 
equal to zero, and if a requested file is not present under the current user number, 
the file system automatically attempts to open the file under user zero. If the file 
exists under user zero, and if it has the system attribute, t2', set, the file is opened ~ 
from user zero. Note, however, that files opened in this way cannot be written to; 
they are available only for read access. This procedure allows utilities that may 
include overlays and any other commonly accessed files to be placed on user zero, _ 
but also be available for access from other user numbers. As a result, commonly 
needed utilities need not be copied to all user numbers on a directory, and you can 
control which user zero files are directly accessible from other user numbers. 



r DIGITAL RESEARCH- 



CP/M 3 Programmer's Guide 



2.3 BDOS File System 



2.3.6 Directory Labels and XFCBs 

The BDOS file system includes two special types of FCBs: the XFCB and the 
Directory Label. The XFCB is an extended FCB that optionally can be associated 
with a file in the directory. If present, it contains the file's password. Note that 
password protected files and XFCBs are supported only in the banked version of 
CP/M 3. The format of the XFCB follows. 



DR 


FILE 


TYPE 


PM 


SI 


S2 


RC 


PASSWORD 


RESERVED 


00 01 . . . 


09.. 


12 13 14 15 


16 


24 



Figure 2-1. XFCB Format 



dr 
file 


drive code (0 ■ 16) 
filename field 


type 
pm 


filetype field 
password mode 
bit 7 - Read mode 




bit 6 - Write mode 




bit 5 - Delete mode 




* • - bit references are right to left 




relative to 


sl,s2,rc - 
password - 

reserved - 


reserved for system use 

8-byte password field (encrypted) 

8-byte reserved area 



n . 



DECITAL RESEARCH' 



2.3 BDOS File System 



CP/M 3 Programmer's Guide 



An XFCB can be created only on a drive that has a directory label, and only if the 
directory label has activated password protection. For drives in this state, an Xf CB 
can be created for a file in two ways: by the BDOS Make function or by the BDOS 
Write File XFCB function. The BDOS Make function creates an XFCB if the calling 
program requests that a password be assigned to the created file. The BDOS Write 
File XFCB function can be used to assign a password to an existing file. Note that in 
the directory, an XFCB is identified by a drive byte value, byte in the FCB, equal 
to 16 + N, where N equals the user number. 

For its drive, the directory label specifies if file password support is to be activated, 
and if date and time stamping for files is to be performed, The format of the Direc- 
tory Label follows. 



DR 


NAME 


TYPE 


Dl 


SI 


S2 


RC 


PASSWORD 


TS1 


TS2 


00 


01 , , 


09, . 


12 13 14 15 


16 


24, 


28 , 



Figure 2-2. Directory Label Format 



dr 

naitie 

type 



sl,s2,rc 
password - 
tsl 
ts2 



drive code {0 - 16) 

Directory Label name 

Directory Label type 

Directory Label data byte 

bit 7 ■ require passwords for password 

protected files 
bit 6 ■ perform access time stamping 
bit 5 - perform update time stamping 
bit 4 - perform create time stamping 
bit - Directory Label exists 
** - bit references are right to left, 

relative to 
nJa 

8-byte password field (encrypted) 
4-byte creation time stamp field 
4-byte update time stamp field 



'irDICITAL RESEARCH- 



CP/M 3 Programmer's Guide 2.3 BDOS File System 

Only one Directory Label can exist in a drive's directory. The Directory Label name 
and type fields are not used to search for 3 Directory Label; they can be used to 
identify a disk. A Direaory Label can be created, or its fields can be updated by 
BDOS function 100, Set Directory Label. This function can also assign a Directory 
Label a password. The Directory Label password, if assigned, cannot be circum- 
vented, whereas file password protection is an option controlled by the Directory 
Label. Thus, access to the Direaory Label password provides a kind of super-user 
status on that drive. 

The nonbanked version of CP/M 3 does not support file passwords. However, it 
does provide password protection of directory labels. The CP/M 3 RSX, DIRLBL,RSX, 
which implements BDOS Function 100 in the nonbanked version of CP/M 3, pro- 
vides this support. 

The BDOS file system has no function to read the Directory Label FCB direaly. 
However, the Directory Label data byte can be read directly with the BDOS Function 
101, Return Directory Label. In addition, the BDOS Search functions, with a ? in the 
FCB drive byte, can be used to find the Directory Label on the default drive. In the 
direaory, the Directory Label is identified by a drive byte value, byte in the FCB, 
equal to 32, 20H. 

2.3.7 File Passwords 

Only the banked version of CP/M 3 supports file passwords. In the nonbanked 
version, all BDOS functions with password related options operate the same way the 
banked version does when passwords are not enabled. 

Files can be assigned passwords in two ways: by the Make File function or by the 
Write File XFCB funaion. A file's password can also be changed by the Write File 
XFCB function if the original password is supplied. 

Password protection is provided in one of three modes. Table 2-4 shows the differ- 
ence in access level allowed to BDOS functions when the password is not supplied. 



n .. 



DrCITAL RESEARCH" - 



2.3 BDOS File System CP/M 3 Programmer's Guide 

Table 2-4. Password Protection Modes 



Password 
Mode 


Access level allowed when the password 
is not supplied. 


1. Read 


The file cannot be read. 


2. Write 


The file can be read, but not modified. 


3. Delete 


The file can be modified, but not 

deleted. 



If a file is password protected in Read mode, ihe password must be supplied to open 
the file. A file protected in Write mode cannot be written to without the password. 
A file protected in Delete mode allows read and write access, but the user must 
specify the password to delete the file, rename the file, or to modify the file's attri- 
butes. Thus, password protection in mode 1 imphes mode 2 and 3 protection, and 
mode 2 protection implies mode 3 protection. All three modes require the user to 
specify the password to delete the file, rename the file, or to modify the file's attributes. 

If the correct password is supplied, or if password protection is disabled by the 
Directory Label, then access to the BDOS functions is the same as for a file thai is 
not password protected. In addition, the Search For First and Search For Next func- 
tions are not affected by file passwords. 

Table 2-5 lists the BDOS functions that test for password. 



Table 2-5. 


BDOS Fijiictian& That Test For Password 


15. 


Open File 


19. 


Delete File 


23. 


Rename File 


30. 


Set File Attributes 


99. 


Truncate File 


100. 


Set Directory Label 


103. 


Write File XFCB 



CP/M 3 Programmer's Guide 



2.3 BDOS File System 



File passwords are eight bytes in length. They are maintained in the XFCB Direc- 
tory Label in encrypted form. To make a BDOS function call for a file that requires 
a password, a program must place the password in the first eight bytes of the current 
DMA, or specify it with the BDOS function. Set Default Password, prior to making 
the function call. 

Note: the BDOS keeps an assigned default password value until it is replaced with a 
new assigned value. 



2.3.8 File Date and Time Stamps 

The CP/M 3 File System uses a special type of directory entry called an SFCB to 
record date and time stamps for files. When a directory has been initialized for date 
and time stamping, SFCBs reside in every fourth position of the direaory. Each SFCB 
maintains the date and time stamps for the previous three directory entries as shown 
in Figure 2-3. 





FCB 1 




FOB 2 




FCB 3 


21 


STAMPS FOR 
FCB1 


STAMPS FOR 
FCB 2 


STAMPS FOR 
FCB 3 





Figure 2-3. Directory Record with SFCB 



This figure shows a directory record that contains an SFCB. Directory records consist 
of four directory entries, each 32 bytes long. SFCBs always occupy the last position 
of a directory record. 

The SFCB directory item contains five fields. The first field is one byte long and 
contains the value 21H. This value identifies the SFCB in the directory. The next 
three fields, the SFCB subfields, contain the date and time stamps for their corre- 
sponding FCB entries in the directory record. These fields are 10 bytes long. The last 
byte of the SFCB is reserved for system use. The format of the SFCB subfields is 
shown in Table 2-6. 



"DIGITAL RESEARCH" 



2.3 BDOS File System 



CP/M 3 Programmer's Guide 



Table 2-6. SFCB Subfields Format 




Offset in Bytes 



SFCB Subfietd Contents 



Create or Access Date and Time Stamp field 
Update Date and Time Stamp field 
Password mode field 
Reserved 



An SFCB subfield contains valid information only if its corresponding FCB in the 
directory record is an extent zero FCB. This FCB is a file's first directory entry. For 
password protected files, the SFCB subfield also contains the password mode of the 
file. This field is zero for files that are not password protected. The BDOS Search and 
Search Next functions can be used to access SFCBs directly. In addition, BDOS 
Function 102 can return the file date and time stamps and password mode for a 
specified file. Refer to Section 3, function 102, for a description of the format of a 
date and time stamp field. 

CP/M 3 supports three types of file stamping: create, access, and update. Create 
stamps record when the file was created, access stamps record when the file was last 
opened, and update stamps record the last time the file was modified. Create and 
access stamps share the same field. As a result, file access stamps overwrite any create 

stamps. 

The CP/M 3 utility, INITDIR, initializes a directory for date and time stamping by 
placing SFCBs in every fourth directory entry. Date and time stamping is not sup- 
ported on disks that have not been initialized in this manner. For initialized disks the 
disks' Directory Label determines the type of date and time stamping supported for 
files on the drive. If a disk does not have a Directory Label, or if it is Read-Only, or 
if the disk's Directory Label does not specify date and time stamping, then date and 
time stamping for files is not performed. Note that the Direaory Label is also time 
stamped, but these stamps are not made in an SFCB. Time stamp fields in the last 
eight bytes of the Directory Label record when it was created and last updated. 
Access stamping for Direaory Labels is not supported. 



CP/M 3 Programmer's Guide 2.3 BDOS File System 

The BDOS file system uses the CP/M 3 system date and time when it records a 
date and time stamp. This value is maintained in a field in the System Control Block 
(SCB). On CP/M 3 systems thai support a hardware dock, the BIOS module directly 
updates the SCB system date and time field. Otherwise, date and time stamps record 
the last initialized value for the system date and time. The CP/M 3 DATE utility can 
be used to set the system date and time. 

2.3.9 Record Blocking and Deblocking 

Under CP/M 3, the logical record size for disk 1/0 is 128 bytes. This is the basic 
unit of data transfer between the operating system and transient programs. However, 
on disk, the record size is not restriaed to 128 bytes. These records, called physical 
records, can range from 128 bytes to 4K bytes in size. Record blocking and deblock- 
ing is required on systems that support drives with physical record sizes larger than 
128 bytes. 

The process of building up physical records from 128 byte logical records is called 
record blocking. This process is required in write operations. The reverse process of 
breaking up physical records into their component 128 byte logical records is called 
record deblocking. This process is required in read operations. Under CP/M 3, record 
blocking and deblocking is normally performed by the BDOS. 

Record deblocking implies a read-ahead operation. For example, if a transient 
program makes a BDOS function call to read a logical record that resides at the 
beginning of a physical record, the entire physical record is read into an internal 
buffer. Subsequent BDOS read calls for the remaining logical records access the 
buffer instead of the disk. Conversely, record blocking results in the postponement 
of physical write operations but only for data write operations. For example, if a 
transient program makes a BDOS write call, the logical record is placed in a buffer 
equal in size to the physical record size. The write operation on the physical record 
buffer is postponed until the buffer is needed in another I/O operation. Note that 
under CP/M 3, directory write operations are never postponed. 

Postponing physical record write operations has implications for some applications 
programs. For those programs that involve file updating, it is often critical to guar- 
antee that the state of the file on disk parallels the state of the file in memory after 
the update operation. This is ordy an issue on systems where physical write opera- 
tions are postponed because of record blocking and deblocking. If the system should 
crash while a physical buffer is pending, data would be lost. To prevent this loss of 
data, the BDOS Flush Buffers function, function 48, can be called to force the write 
of any pending physical buffers. 



m DIOnAL RESEARCH" 



2.3 BDOS File System CP/M 3 Programmer's Guide 

Note: the CCP automatically discards all pending physical data buffers when it 
receives control following a system warm start. However, the BDOS file system 
automatically makes a Flush Buffers call in the Close File function. Thus, it is suffi- 
cient to close a file to ensure that all pending physical buffers for that file are written 
to the disk. 

2.3.10 Multi-Sector I/O 

CP/M 3 can read or write multiple 128-byte records in a single BDOS funaion 
call. This process, called multi-sector I/O, is useful primarily in sequenrial read and 
write operations, particularly on drives with physical record sizes larger than 128 
bytes. In a multi-sector I/O operation, the BDOS file system bypasses, when possible, 
all intermediate record buffering. Data is transferred directly between the TPA and 
the drive. In addition, the BDOS informs the BIOS when it is reading or writing 
multiple physical records in sequence on a drive. The BIOS can use this information 
to further optimize the I/O operation resulting in even better performance. Thus, the 
primary objective of multi-sector I/O is to improve sequential I/O performance. The 
actual improvement obtained, however, depends on the hardware environment of the 
host system, and the implementation of the BIOS. 

The number of records that can be supported with multi-sector I/O ranges from 1 
to 128. This value can be set by BDOS function 44, Set multi-seaor Count. The 
multi-sector count is set to one when a transient program begins execution. However, 
the CP/M 3 LOADER module executes with the multi-sector Count set to 128 unless 
the available TPA space is less than 16K. In addition, the CP/M 3 PIP utility also 
sets the multi-sector count to 128 when sufficient buffer space is available. Note that 
the greatest potential performance increases are obtained when the multi-sectot count 
is set to 128. Of course, this requires a 16K buffer. 

The multi-seaor count determines the number of operations to be performed by 
the following BDOS functions: 

■ Sequential Read and Write functions 

■ Random Read and Write functions including Write Random with Zero Fill 

If the multi-seaor count is N, calling one of the above functions is equivalent to 
making N function calls. If a multi-seaor I/O operation is interrupted with an error 
such as reading unwritten data, the file system returns in register H the number of 
128-byte records successfully processed. 



ffiDIGnAL RESEARCH' 



^ CP/M 3 Programmer's Guide 2.3 BDOS File System 

2.3.11 Disk Reset and Removable Media 

n The BDOS functions, Disk Reset (function 13) and Reset Drive (function 37) allow 

a program to control when a disk's directory is to be reinitialized for file operations. 

This process of initializing a disk's direaory is called logging-in the drive. When 

! I CP/M 3 is cold started, all drives are in the reset state. Subsequently, as drives are 

i referenced, they are automatically logged-in by the file system. Once logged-in, a 

drive remains in the logged-in state until it is reset by BDOS function 13 or 37. 
^ Following the reset operation, the drive is again automatically logged-in by the file 
, , system when it is next used. Note that BDOS functions 13 and 37 have similar effects 

except that function 13 is directed to all drives on the system. Any combination of 
_ drives can be reset with Function 37. 

Logging-in a drive consists of several steps. The most imponant step is the initiali- 
zation of the drive's allocation vector. The allocation vector records the allocation 
rj and deallocation of data blocks to files, as files are created, extended, deleted, and 
• I truncated. Another function performed during drive log-in is the initialization of the 
directory check-sum vector. The file system uses the check -sum vector to detect media 
^m, changes on a drive. Note that permanent drives, which are drives that do not support 
' media changes, might not have check-sum vectors. If directory hashing has been 

specified for the drive, a BIOS and GENCPM option, the file system creates a hash 
table for the directory during log-in. 

' ' The primary use of the drive reset functions is to prepare for a media change on a 

drive. Subsequently, when the drive is accessed by a BDOS function call, the drive is 

r^ automatically logged-in. Resetting a drive has two important side effects. First of all, 

i I any pending blocking/deblocking buffers on the reset drive are discarded. Secondly, 
any data blocks that have been allocated to files that have not been closed are lost. 

„ An application program should close files, particularly files that have been written to, 

I ] prior to resetting a drive. 

Although CP/M 3 automatically relogs in removable media when media changes 

nare detected, the application program should still explicitly reset a drive before 
prompting the user to change disks. 



n ™ 



DIGFTAL RESEARCH" 



2.3 BDOS File System CP/M 3 Programmer's Guide 

2.3.12 File Byte Counts 

Although the logical record size of CP/M 3 is restriaed to 128 bytes, CP/M 3 does 
provide a mechanism to store and retrieve a byte count for a file. This facility can 
identify the last byte of the last record of a file. The BDOS Compute File Size 
function returns the random record number, plus 1, of the last record of a file. 

The BDOS Set File Attributes function can set a file's byte count. Conversely, the 
Open function can return a file's byte count to the cr field of the FCB. The BDOS 
Search and Search Next functions also return a file's byte count. These funaions 
return the byte count in the si field of the FCB returned in the current DMA buffer 
(see BDOS Functions Returned 17 and 26). 

Note that the file system does not access or update the byte count value in file read 
or write operations. However, the BDOS Make File function does set the byte count 
of a file to zero when it creates a file in the directory. 

2.3.13 BDOS Error Handling 

The BDOS file system responds to error situations in one of three ways: 

Method 1. it returns to the calling program with return codes in register 

A, H, and L identifying the error. 

Method 2. It displays an error message on the console, and branches to 

the BIOS warm start entry point, thereby terminating execu- 
tion of the calUng program. 

Method 3, It displays an error message on the console, and returns to 

the calling program as in method 1. 

The file system handles the majority of errors it deteas by method 1. Two examples 
of this kind of error are the file not found error for the open function and the reading 
unwritten data error for a read function. More serious errors, such as disk I/O errors, 
are usually handled by method 2. Errors in this category, called physical and extended 
errors, can also be reported by methods 1 and 3 under program control. 



SEDICrrAL RESEARCH' 



-. CP/M 3 Programmer's Guide 2.3 BDOS File System 

The BDOS Error Mode, which can exist in three states, determines how the file 

^ system handles physical and extended errors. In the default state, the BDOS displays 

I 1 the error message, and terminates the calling program, method 2. In return error 

mode, the BDOS returns control to the calling program with the error identified in 

,-1 registers A, H, and L, method 1. In return and display mode, the BDOS returns 

' control to the calling program with the error identified in registers A, H, and L, and 

also displays the error message at the console, method 3. While both return modes 

protect a program from termination because of a physical or extended error, the 

return and display mode also allows the catling program to take advantage of the 

' built-in error reporting of the BDOS file system. Physical and extended errors are 

displayed on the console in the following format: 

, CP/M Error on d: error message 

BDOS function = nn File = filename.typ 

i I where d identifies the drive seleacd when the error condition is deteaed; error mes- 
' ' sage identifies the error; nn is the BDOS funaion number, and filename.typ identifies 

the file specified by the BDOS function, If the BDOS function did not involve an 
PJ FCB, the file information is omined. Note that the second line of the above error 
; I message is displayed only in the banked version of CP/M 3 if expanded error message 

reporting is requested in GENCPM, It is not displayed in the nonbanked version of 
^ CP/M 3. 

The BDOS physical errors are identified by the following error messages: 

"^ ■ Disk I/O 

' ■ Invalid Drive 

■ Read-Only File 

|~ ■ Read-Only Disk 

The Disk I/O error results from an error condition returned to the BDOS from the 
fm, BIOS module. The file system makes BIOS read and write calls to execute file-related 
' I BDOS calls. If the BIOS read or write routine deteas an error, it returns an error 

code to the BDOS resulting in this error. 

^ The Invalid Drive error also results from an error condition returned to the BDOS 

1 \ from the BIOS module. The BDOS makes a BIOS SeleCT Disk call prior to accessing 
a drive to perform a requested BDOS function. If the BIOS does not support the 
^^ selected disk, the BDOS returns an error code resulting in this error message. 



M DIGITAL RESEARCH' 



2.3 BDOS File System CP/M 3 Programmer's Guide — 

The Read-Only File error is returned when a program attempts to write to a file 
that is marked with the Read-Only attribute. It is also returned to a program that "" 
attempts to write to a system file opened under user zero from a nonzero user 
number. In addition, this error is returned when a program attempts to write to a 
file password protected in Write mode if the program does not supply the correct ». 
password. 

The Read-Only Disk error is returned when a program writes to a disk that is in 
read-only status. A drive can be placed in read-only status explicitly with the BDOS "" 
Write Protect Disk function. 

The BDOS extended errors are identified by the following error messages: f~ 

■ Password Error 

■ File Exists ^ 

■ ? in Filename I I 

The File Password error is returned when the file password is not supplied, or 
when it is incorrect. This error is reported only by the banked version of CP/M 3. ^ 

The File Exists error is returned by the BDOS Make File and Rename File func- 
tions when the BDOS detects a conflict such as a duplicate filename and type. — 

The ? in Filename error is returned when the BDOS deteas a ? in the filename or 
type field of the passed FCB for the BDOS Rename File, Set File Attributes, Open ^ 
File, Make File, and Truncate File functions. 

The following paragraphs describe the error return code conventions of the BDOS 
file system functions. Most BDOS file system functions fall into three categories in "" 
regard to return codes: they return an Error Code, a Directory Code, or an Error 
Flag. The error conventions of CP/M 3 are designed to allow programs written for 
earlier versions of CP/M to run without modification. _ 

The following BDOS functions return an Error Code in register A. 

20. Read Sequential *" 

21. Write Sequential i 

33. Read Random 

34. Write Random h. 
40. Write Random w/Zero Fill I 



a DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



2.3 BDOS File System 



The Error Code definitions for register A are shown in Table 2-7. 



Table 2-7. Register A BDOS Error Codes 



Code 


1 Meaning 


00 


Funaion successful 


255 


Physical error ; refer to register H 


01 


Reading unwritten data or no available diteaory space (Write 




Sequential) 


02 


No available data block 


03 


Cannot close current extent 


04 


Seek to unwritten extent 


05 


No available directory space 


06 


Random record number out of range 


09 


Invalid FCB (previous BDOS close call returned an error code 




and invalidated the FCB) 


10 


Media Changed (A media change was detected on the FCB's 




drive after the FCB was opened) 



For BDOS read or write functions, the file system also sets register H when the 
returned Error Code is a value other than zero or 255. In this case, register H 
contains the number of 128-byte records successfully read or wrinen before the error 
was encountered. Note that register H can contdln only a nonzero value if the calUng 
program has set the BDOS Multi-Seaor Count to a value other than one; otherwise 
register H is set to zero. On successful funaions. Error Code = 0, register H is also 
set to zero. If the Error Code equals 255, register H contains a physical error code 
(see Table 2-11). 



E DIGITAL RESEARCH'" 



2.3 BDOS File System 



The following BDOS fui 



return a Directory Code in register A: 



15. Open File 

16. Close File 

17. Search For First 

18. Search For Next 

19. Delete File 

22. Make File 

23. Rename File 

30. Set File Attributes 
35, Compute File Size 
99. Truncate File 

* 100. Set Direaory Label 

102. Read File Date Stamps and Password Mode 
•• 103. Write File XFCB 

• - This function is supported in the DIRLBL.RSX in the nonbanked version of 

CP/M 3. 
*• - This function is supported only in the banked version of CP/M 3. 

The Directory Code definitions for register A are shown in Table 2-8. 



Table 2-8. 


BDOS Directory Codes 


Code 


I Meaning 


00 — 03: 
255 


successful function 
unsuccessful function 



With the exception of the BDOS search functions, all functions in this category 
return with the directory code set to zero on successful returns. However, for the 
search functions, a successful Directory Code also identifies the relative starting posi- 
tion of the directory entry in the calling program's current DMA buffer. 



- il DIGITAL RESEARCH' 



^ CP/M 3 Programmer's Guide 



2.3 BDOS File System 



If the Set BDOS Error Mode function is used to place the BDOS in return t 
mode, the following functions return an Error Flag on physical errors: 

14. Select Disk 
46. Get Disk Free Space 
48. Flush Buffers 
98. Free Blocks 
101. Return Direaory Label Data 



The Error Flag defini 



1 for register A is shown in Table 2-9. 



Table 2-9. BDOS Error Flags 



Meaning 



00 
255 



successful function 

physical error : refer to register H 



The BDOS returns nonzero values in register H to identify a physical or extended 
error if the BDOS Error Mode is in one of the return modes. Except for functions 
that return a Direaory Code, register A equal to 255 indicates that register H iden- 
tifies the physical or extended error. For functions that return a Directory Code, if 
register A equals 255, and register H is not equal to zero, register H identifies the 
physical or extended error. Table 2-10 shows the physical and extended error codes 
returned in register H. 



2.3 BDOS File System 



CP/M 3 Programmer's Guide "* 



Table 2-10. 


BDOS Physical and Extended Errors 


Code 


1 Meaning 


00 — 


no error, or not a register H error 


01 — 


Disk I/O error 


02 — 


Read-Only Disk 


03 — 


Read-Only File or File Opened 




under user zero from another user 




number or file password protected 




in write mode and correct pass- 




word not specified. 


04 — 


Invalid Drive : drive select error 


07 — 


Password Error 


08 — 


File Exists 


09 — 


? in Filename 



The following two functions represent a special case because diey return an address 
in registers H and L. 

27. Get Addr(Alloc) 

31. Get Addr(Disk Farms) 

When the BDOS is in return error mode, and it detects a physical error for these 

functions, it returns to the calling program with registers A, H, and L all set to 255. 
Otherwise, they return no error code. 



2.4 Page Zero Inidalizadon 

Page Zero is the region of memory located from OOOOH to OOFFH. This region 
contains several segments of code and data that are used by transient programs while 
running under CP/M 3. The code and data areas are shown in Table 2-11 for reference. 



- B DIGITAL RESEARCH" 



-^ CP/M 3 Programmer's Guide 



2.4 Page Zero Initial 



Tabic 2-11. Page Zero Areas 



From To 

OOOOH — 0002H Contains a jump instruction to the BIOS warm start entry 
point at BIOS_base + 3. The address at location OOOIH can 
also be used to make direct BIOS calls to the BIOS console 
status, console input, console output, and list output primitive 
functions. 

0003H — 0004H (Reserved) 

0005H — 0007H Contains a jump instruction to the BDOS, the LOADER, or 
to the most recently added RSX, and serves two purposes: 
JMP 0005H provides the primary entry point to the BDOS, 
and LHLD 0006H places the address field of the jump 
instruction in the HL register pair. This value, minus one, is 
the highest address of memory available to the transient 
program. 

0008H — 003AH Reserved interrupt locations for Restarts 1 - 7 



003BH — 004FH (Not currently used 

0050H Identifies the drive from which the transient program was load- 

ed, A value of one to sixteen identifies drives A through P. 

005 IH — 0052H Contains the address of the password field of the first command- 
tail operand in the default DMA buffer beginning at 0080H. 
The CCP sets this field to zero if no password for the first 
command-tail operand is specified. 

0053H Contains the length of the password field for the first command- 

tail operand. The CCP also sets this field to zero if no password 
for the first command tail is specified. 

0054H — 0055H Contains the address of the password field of the second com- 
mand-tail operand in the default DMA buffer beginning at 
0080H, The CCP sets this field to zero if no password for the 
second command- tail operand is specified. 



BDICITAL RESEARCH'' 



2.4 Page Zero Initialization CP/M 3 Programmer's Guide 

Table 2-11. (continued) 



Location 


Contents 


From 
0056H 


To 


Contains the length of the password field for the second com- 
mand-tail operand. The CCP also sets this field to zero if no 

password for the second command tail is specified. 


005 7H — 


005BH 


(Not currently used - reserved) 


005 CH — 


007BH 


Default File Control Block, FCB, area 1 initialized by the CCP 

from the first command-tail operand of the command line, if 
it exists. 


006CH - 


007BH Default File Control Block, FCB, area 2 initialized by the CCP 
from the second command-tail operand of the command line, 
if it exists. 






Note: this area overlays the last 16 bytes of default FCB 
area 1. To use the information in this area, a transient program 
must copy it to another location before using FCB area 1. 


007CH 




Current record position of default FCB area 1. This field is used 
with default FCB area 1 in sequential record processing. 


007DH — 


007FH 


Optional default random record position. This field is an exten- 
sion of default FCB area 1 used in random record processing. 


0080H — 


OOFFH 


Default 128-byie disk buffer. This buffer is also filled with the 
command tail when the CCP loads a transient program. 



IT DIGITAL RESEARCH* 



CP/M 3 Programmer's Guide 2.4 Page Zero Initialization 

The CCP initializes Page Zero prior to initiating a transient program. The fields at 
0050H and above are initialized from the command line invoking the transient pro- 
gram. The command line format was described in detail in Section 1.6.2. To sum- 
marize, a command line usually takes the form: 

<command> <command tail> 

where 



<command> = > <file speO 

<command tail> = > (no command tail) 
= > <file speO 
= > <fite spec >< delimiter >< file spec> 

<file speO = > {d:}filename{.type} {;password} 

The CCP initializes the command drive field at 0050H to the drive index, A = 1, ..., 
P = 16, of the drive from which the transient program was loaded. 

The default FCB at 005CH is defined if a command tail is entered. Otherwise, the 
fields at 005CH, 0068H to 006BH are set to binary zeros, the fields from 005DH to 
0067H are set to blanks. The fields at 0051H through 0053H are set if a password 
is specified for the first <file spec> of the command tail. If not, these fields are set to 



The default FCB at 006CH is defined if a second <filc spec> exists in the com- 
mand tail. Otherwise, the fields at 006CH, 0078H to 007BH are set to binary zeros, 
the fields from 005DH to 0067H are set to blanks. The fields at 0054H through 
0056H are set if a password is specified for the second <file speO of the command 
tail. If not, these fields are set to zero. 

Transient programs often use the default FCB at OOJCH for file operations. This 
FCB may even be used for random file access because the three bytes starting at 
007DH are available for this purpose. However, a transient program must copy the 
contents of the default FCB at 006CH to another area before using the default FCB 
at 005CH, because an open operation for rfie default FCB at 005CH overwrites the 
FCB data at 006CH. 



U DICFTAL RESEARCH* 



2.4 Page Zero Initialization CP/M 3 Programmer's Guide 

The default DMA address for transient programs is 0080H. The CCP also initial- 
izes this area to contain the command tail of the command line. The first position 
contains the number of characters in the command line, followed by the command 
line characters. The character following the last command tail charaaer is set to 
binary zero. The command line characters are preceded by a leading blank and are 
translated to ASCII upper-case. Because the 128-byte region beginning at 0080H is 
the default DMA, the BDOS file system moves 128-byte records to this area with 
read operations and accesses 128-byte records from this area with write operations. 
The transient program must extract the command tail information from this buffer 
before performing file operations unless it explicitly changes the DMA address with 
the BDOS Set DMA Address function. 

The Page Zero fields of 0051H through 0056H locate the password fields of the 
first two file specifications in the command tail if they exist. These fields are provided 
so that transient programs are not required to parse the command tail for password 
fields. However, the transient program must save the password, or change the DMA 
address before performing file operations. 

The following example illustrates the initialization of the command line fields of 
Page Zero. Assuming the following command line is typed at the console: 

D > A: PROGRAM B : FILE ,TYPE i PASS C >F ILE . TVPE i PASSWORD 

A hexadecimal dump of 0050H to 00A5H would show the Page Zero initialization 
performed by the CCP. 



0050H: 
OOEOHi 
0070HI 
0080H: 
OOgOH: 



01 8D 00 Oa 90 00 08 00 00 00 00 00 02 AG 03 ac FIL 

as zo 20 20 20 sa ss so oo oo 00 00 03 aG ag ac e-.-.tvp fil 

as zo 20 zo zo Sa 59 so oo oo 00 00 00 00 00 00 E,...TVP 

za zo az an as ag ac as 2e sa ss so 38 so ai 53 , BiFiUE.TVPSPAS 

S3 zo a3 3fi ag ag ac as 2E sa sg so 3B so ai S3 s cjFiLE.TVPiPAS 



OOflOHt S3 57 ap 52 aa 00 SUOftD. 



End of Section 2 



Section 3 
BDOS Function Calls 



This section describes each CP/M 3 system function, including the parameters a 
program must pass when calling the function, and the values the function returns to 
the program. The functions are arranged numerically for easy reference. You should 
be familiar with the BDOS calling conventions and other concepts presented in Section 2 
before referencing this S' 



BDOS FUNCTION 0: SYSTEM RESET 



Entry Parameters: 

Register C: OOH 



The System Reset function terminates the calling program and returns control to 
the CCP via a warm start sequence (see Section 1.3,2). Calling this function has the 
same effect as a jump to location OOOOH of Page Zero. 

Note thai the disk subsystem is not reset by System Reset under CP/M 3, The 
calling program can pass a return code to the CCP by calling Funaion 108, Get/Set 
Program Return Code, prior to making a System Reset call or jumping to location 
OOOOH. 



B DIGITAL RESEARCH'" - 



3 BDOS Calls: Function 1 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 1; CONSOLE INPUT 



Entry Parameters: 

Register C: OIH 



Returned Value: 

Register A: ASCII Chararter 



The Console Input function reads the next character from the logical console, 
CONIN:, to register A. Graphic characters, along with carriage return, line-feed, and 
backspace, CTRL-H, are echoed to the console. Tab characters, CTRL-I, are expanded 
in columns of 8 chararters. CTRL-S, CTRL-Q, and CTRL-P are normally intercepted 
as described below. All other non-graphic characters are returned in register A but 
are not echoed to the console. 



When the Console Mode is in the default state {see Section 2.2.1), Function 1 
intercepts the stop scroll, CTRL-S, start scroll, CTRL-Q, and start/stop printer echo, 
CTRL-P, characters. Any characters that are typed following a CTRL-S and preced- 
ing a CTRL-Q are also intercepted. However, if start/stop scroll has been disabled 
by the Console Mode, the CTRL-S, CTRL-Q, and CTRL-P charaaere are not inter- 
cepted. Instead, they are returned in register A, but are not echoed to the console. 



If printer echo has been invoked, all characters that < 
also sent to the list device, LST:. 



e echoed to the console a 



Function 1 does not return control to the caUing program until a non-intercepted 
character is typed, thus suspending execution if a charaaer is not ready. 



- EDIOiTAL RESEARCH* 



*! CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 2 



BDOS FUNCTION 2: CONSOLE OUTPUT 



Entry Parameters: 

Registers C: 02H 

E: ASCII Character 



The Console Output function sends the ASCII character from register E to the 
logical console device, CONOUT:. When the Console Mode is in the default state 
(see Section 2.2.1), Function 2 expands tab characters, CTRL-I, in columns of 8 
characters, checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes charac- 
ters to the logical list device, LST:, if printer echo, CTRL-P, has been invoked. 



n ,, 



DIGITAL fiESEARCH" - 



3 BDOS Calls: Function 3 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 3: AUXILIARY INPUT 



Entry Parameters: 

Register C; 03H 



Returned Value: 

Register A: ASCII Charaaer 



The Auxiliary Input function reads the next character from the logical auxiliary 
nput device, AUXIN:, into register A, Control does not return to the calling program 
jntil the character is read. 



- II DICrXAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 4 



BDOS FUNCTION 4: AUXILIARY OUTPUT 



Entry Parameters: 

Registers C: 04H 

E: ASCII Character 



The Auxiliary Output function sends the ASCII character from register E to the 
logical auxiliary output device, AUXOUT:. 



n . 



DIGITAL RESEARCH'" 



3 BDOS Calls: Function S 



CP/M 3 Programmer's Guide 



BDOS FUNCTION S-. LIST OUTPUT 



Entry Parameters: 

Registers C: 05H 

G: ASCII Character 



The List Output function sends the ASCII character in register E to the logical list 
device, LST:. 



EDICITM RESEARCH' 



"1 CP/M 3 Programmer's Guide 

n 



3 BDOS Calls; Function 6 



BDOS FUNCTION 6: DIRECT CONSOLE 1/0 



Entry Parameters: 

Registers C: 06H 

E: OFFFi (input/status) or 
OFEH (status) or 
OFDFl (input) or 
char (output) 

Returned Value: 

Register A: char or status (no value) 



nCP/M 3 supports direct I/O to the logical console, CONIN:, for those specialized 
applications where unadorned console input and output is required. Use Direct Con- 
sole I/O carefully because it bypasses all the normal control character functions. 
Programs that perform direct I/O through the BIOS under previous releases of CP/M 
n should be changed to use direct I/O so that they can be fully supported under future 
I I releases of MP/M and CP/M. 

^^ A program calls Function 6 by passing one of four different values in register E. 

I The values and their meanings arc summarized Jn Table 3-1. 



3 BDOS Calls: Function 6 



CP/M 3 Programmer's Guide 



Table 3-1. Function 6 Entry Parameters 



Register 

E value 



Meaning 



ASCII 
character 



Console input/status command returns an input chatacter; if no 
character is ready, a value of zero is returned. 



Console status command COn return, register A contains 00 if no 
character is ready; otherwise it contains FFH.} 



Console input command, returns an input character; this func- 
tion will suspend the calling process until a character is ready. 



Function 6 assumes that register E contains a valid ASCII char- 
acter and sends it to the console. 



CP/M 3 Programmer's Guide 



3 BDOS Calls; Function 7 



BDOS FUNCTION 7: AUXILIARY INPUT STATUS 



Entry Parameters: 

Register C: 07H 



Returned Value: 

Register A: Auxiliary Input Status 



The Auxiliary Input Status function returns the value OFFH in register A if a 
character is ready for input from the logical auxiliary input device, AUXIN:. If no 
character is ready for input, the value OOH is returned. 



n . 



S?) DIGITAL RESEARCH* 



3 BDOS Calls: Function 8 



CP/M 3 Programmer's Guide "^ 



BDOS FUNCTION S: AUXILIARY OUTPUT STATUS 



Entry Parameters: 

Register C: 08H 



Returned Value: 

Register A: Auxiliary Output Status 



The Auxiliary Output Status function returns the value OFFH in register A if the 
logical auxiliary output device, AUXOUT;, is ready to accept a character for output. 
If the device is not ready for output, the value OOH is returned. 



- m DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 9 



BDOS FUNCTION 9; PRINT STRING 



Entry Parameters: 

Registers C: 09H 

DE: String Address 



The Print String function sends the character string addressed by register pair DE 
to the logical console, CONOUT:, until it encounters a delimiter in the string. Usu- 
ally the delimiter is a dollar sign, $, but it can be changed to any other value by 
Function 110, Get/Set Output Delimiter. If the Console Mode is in the defauh state 
(see Section 2.2.1), Function 9 expands tab characters, CTRL-I, in columns of 8 
charaaers. It also checks for stop scroll, CTRL-S, start scroll, CTRL-Q, and echoes 
to the logical list device, LST:, if printer echo, CTRL-P, has been invoked. 



UDECiTAL RESEARCH' 



3 BDOS Calls: Function 10 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 10: READ CONSOLE BUFFER 



Entry Parameters: 

Registers C: OAH 

D£: Buifer Address 

Returned Value: 

Console Characters in Buffer 



The Read Console Buffer function reads a line of edited console input from the 
logical console, CONIN:, to a buffer that register pair DE addresses. It terminates 
input and returns to the calling program when it encounters a return, CTRL-M, or a 
line feed, CTRL-J, character. Function 10 also discards all input characters after the 
input buffer is Blled. In addition, it outputs a bell charaaer, CTRL-G, to the console 
when it discards a character to signal the user that the buffer is full. The input buffer 
addressed by DE has the following format: 



DE: +0 +1 +2 +3 



+ 7 +8 



mx 


„c 


cl 


c2 


c3 


c4 


c5 


c6 


c7 




?? 



where mx is the maximum number of characters which the buffer holds, and nc is 
the number of characters placed in the buffer. The characters entered by the operator 
follow the nc value. The value mx must be set prior to making a Function 10 call 
and may range in value from 1 to 255. Sening mx to zero is equivalent to setting rax 
to one. The value nc is returned to the calling program and may range from zero to 
mx. If nc < mx, then uninitialized positions follow the last charaaer, denoted by ?? 
in the figure. Note that a terminating return or line feed character is not placed in 
the buffer and not included in the count nc. 

If register pair DE is set to zero. Function 10 assumes that an initialized input 
buffer is located at the current DMA address (see Function 26, Set DMA Address). 
This allows a program to put a string on the screen for the user to edit. To initialize 
the input buffer, set characters cl through en to the initial value followed by a binary 
zero terminator. 



■«DIGiTAL RESEARCH- 



CP/M 3 Programmer's Guide 



3 BDOS Calls; Function 10 



When a program calls Function 10 with an initialized buffer, Function 10 operates 
as if the user had typed in the string. When Function 10 encounters the binary zero 
terminator, it accepts input from the console. At this point, the user can edit the 
initialized string or accept it as it is by pressing the RETURN key. However, if the 
initialized string contains a return, CTRL-M, or a linefeed, CTRL-J, character, Func- 
tion 10 returns to the calling program without giving the user the opportunity to edit 
the string. 

The level of console editing supported by Function 10 differs for the banked and 
nonbankcd versions of CP/M 3. Refer to the CP/M Plus (CP/M Version 3) Operating 
System User's Guide for a detailed description of console editing. In the nonbanked 
version, Function 10 recognizes the edit control characters summarized in Table 3-2. 



Table 3-2. Edit Control Characters (Nonbanked CP/M 3) 



Character 


Edit Control Function 


rub/del 


Removes and echoes the last character; GENCPM can change 
this function to CTRL-H 


CTRL-C 


Reboots when at the beginning of line; the Console Mode can 
disable this function 


CTRL-E 


Causes physical end of line 


CTRL-H 


Backspaces one charaacr position; GENCPM can change this 
function to rub/del 


CTRL-J 


(Line-feed) terminates input line 


CTRL-M 


(Return) terminates input line 


CTRL-P 


Echoes console output to the list device 


CTRL-R 


Retypes the current line after new line 


CTRL-U 


Removes current line after new line 


CTRL-X 


Backspaces to beginning of current line 



I' DIGITAL RESEARCH' 



3 BDOS Calls: Function 10 



CP/M 3 Programmer's Guide 



The banked version of CP/M 3 expands upon the editing provided in the non- 
banked version. The functionality of the two versions is similar when the cursor is 
positioned at the end of the line. However, in the banked version, the user can move 
the cursor anywhere in the current line, insert characters, delete characters, and 
perform other editing functions. In addition, the banked version saves the previous 
command line; it can be recalled when the current line is empty. Table 3-3 summa- 
rizes the edit control characters supported by Funaion 10 in the banked version of 
CP/M 3. 



Table 3-3. Edit Control Characters (Banked CP/M 3) 



Character 


Edit Control Function 


rub/del 


Removes and echoes the last charaaer if at the end of the line; 
otherwise deletes the character to the left of the current cursor 
position; GENCPM can change this function to CTRL-H. 


CTRL-A 


Moves cursor one character to the left. 


CTRL-B 


Moves cursor to the beginning of the line when not at the begin- 
ning; otherwise moves cursor to the end of the hne. 


CTRL-C 


Reboots when at the beginning of line; the Console Mode can 
disable this function. 


CTRL-E 


Causes physical cnd-of-line; if the cursor is positioned in the 
middle of a line, the characters at and to the right of the cursor 
are displayed on the next line. 


CTRL-F 


Moves cursor one character to the right. 


CTRL-G 


Deletes the character at the current cursor position when in the 
middle of the line; has no effect when the cursor is at the end of 
the line. 


CTRL-H 


Backspaces one charaaer position when positioned at the end 
of the line; otherwise deletes the charaaer to the left of the 
cursor; GENCPM can change this funaion to rub/del. 



I'DICrTAL RESEARCH- 



CP/M 3 Programmer's Guide 3 BDOS CaUs: Function 10 

Table 3-3. (continued) 



Character 



Edit Control Function 



CTRL-J 



CTRL-P 
CTRL-R 
CTRL-U 

CTRL-W 



[Line-feed) terminates input; the cursor can be positioned any- 
where in the line; the entire input line is accepted; sets the pre- 
vious line buffer to the input line. 



Deletes all characters to the right of the c 
character at the cursor. 



r along with the 



(Return) terminates input; the cursor can be positioned any- 
where in the line; the entire input line is accepted; sets the pre- 
vious line buffer to the input line. 

Echoes console output to the hst device. 

Retypes the characters to the left of the cursor on the new line. 

Updates the previous line buffer to contain the characters to the 
left of the cursor; deletes current line, and advances to new line. 

Recalls previous line if current line is empty; otherwise moves 
cursor to end-of-Une. 

Deletes all chatacteis to the left of the cursor. 



For banked systems, Funaion 10 uses the console width field defined in the System 
Control Block. If the console width is exceeded when the cursor is positioned at the 
end of the line, Function 10 automatically advances to the next line. The beginning 
of the line can be edited by entering a CTRL-R. 

When a character is typed while the cursor is positioned in the middle of the line, 
the typed character is inserted into the line. Characters at and to the right of the 
cursor are shifted to the right. If the console width is exceeded, the characters disap- 
pear off the right of the screen. However, these characters are not lost. They reappear 
if charaaers are deleted out of the line, or if a CTRL-E is typed. 



!<! DIGITAL RESEARCH' 



3 BDOS Calls: Function 11 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 11: GET CONSOLE STATUS 



Entry Parameters: 

Register C: OBH 



Returned Value: 

Register A: Console Status 



The Get Console Status funaion checks to see if a character Has been typed at 
the logical console, CONIN:. If the Console Mode is in the default state (see 
Section 2.2.1}, Funaion 11 returns the value OIH in register A when a character is 
ready. If a character is not ready, it returns a value of OOH. 

If the Console Mode is in CTRL-C Only Status mode, Function 11 returns the 
value OIH in register A only if a CTRL-C has been typed at the console. 



- gilDIClTAL RESEARCH' 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Functic 



BDOS FUNCTION 12: RETURN VERSION NUMBER 



Entry Parameters: 
Register C; 



Returned Value: 

Register HL: Version Number 



The RetuTD Version Number function provides information that allows version 
independent programming. It returns a two-byte value in register pair HL: H con- 
tains OOH for CP/M and L contains 31H, the BDOS file system version number. 
Function 12 is useful for writing applications programs that must run on multiple 
■ s of CP/M and MP/M. 



3 BDOS Calls: Function 13 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 13: RESET DISK SYSTEM 



Entry Parameters: 

Register C: ODH 



The Reset Disk System funaion restores the file system to a reset state where all 
the disk drives are set to read-write (see Functions 28 and 29), the default disk is set 
to drive A, and the default DMA address is reset to 0080H. This function can be 
used, for example, by an application program that requires disk changes during 
operation. Funaion 37, Reset Drive, can also be used for this purpose. 



U DIGITAL RESEARCH- 



"~ CP/M 3 Programmer's Guide 



BDOS FUNCTION 14: SELECT DISK 



Entry Parameters; 

Registers C: OEH 

E: Selected Disk 

Returned Value: 

Registers A: Error Flag 

H: Physical Error 



The Select Disk function designates the disk drive named in register E as the 
default disk for subsequent BDOS file operations. Register E is set to for drive A, 
1 for drive B, and so on through 15 for drive P in a full 16-drive system. In addition, 
Function 14 logs in the designated drive if it is currently in the reset state. Logging- 
in a drive activates the drive's directory until the next disk system reset or drive reset 
operation. 

FCBs that specify drive code zero (dr = OOH) automatically reference the currently 
selected default drive, FCBs with drive code values between 1 and 16, however, 
ignore the selected default drive and directly reference drives A through P. 

Upon return, register A contains a zero if the select operation was successful. If a 
physical error was encountered, the select function performs different actions depend- 
ing on the BDOS error mode (see Function 45). If the BDOS error mode is in the 
default mode, a message identifying the error is displayed at the console, and the 
calling program is terminated. Otherwise, the selea function returns to the calling 
program with register A set to OFFH and register H set to one of the following 
physical error codes: 

01 : Disk I/O Error 
04 : Invalid drive 



m DICtTAL RESEARCH' 



3 BDOS Calls: Function 15 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 15: OPEN FILE 



Entry Parameteis: 

Registers C: OFH 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended Error 



The Open File function activates the FCB for a file that exists in the disk direaory 
under the currently active user number or user zero. The calling program passes the 
address of the FCB in register pair DE, with byte of the FCB specifying the drive, 
bytes 1 through 1 1 specifying the filename and filetype, and byte 12 specifying the 
extent. Usually, byte 12 of the FCB is initialized to zero. 

If the file is password protected in Read mode, the correct password must be 
placed in the first eight bytes of the current DMA, or have been previously estab- 
lished as the default password (see Function 106). If the current record field of the 
FCB, cr, is set to OFFH, Funaion 15 returns the byte count of the last record of the 
file in the cr field. You can set the last record byte count for a file with Function 30, 
Set File Attributes. Note that the current record field of the FCB, cr, must be zeroed 
by the calling program before beginning read or write operations if the file is to be 
accessed sequentially from the first record. 

If the current user is non-zero, and the file to be opened does not exist under the 
current user number, the open function searches user zero for the file. If the file exists 
under user zero, and has the system attribute, t2', set, the file is opened under user 
zero. Write operations are not supported foe a file that is opened under user zero in 
this manner. 



- m DIGITAL RESEARCH ' 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 15 

If the open operation is successful, the user's FCB is activated for read and write 
operations. The relevant direaory information is copied from the matching directory 
FCB into bytes dO through dn of the FCB. If the file is opened under user zero when 
the current user number is not zeio, interface attribute f8' is set to one in the user's 
FCB. In addition, if the referenced file is password protected in Write mode, and the 
correct password was not passed in the DMA, or did not match the default pass- 
word, interface attribute f7' is set to one. Write operations are not supported for an 
activated FCB if interface attribute f7' or f8' is true. 

When the open operation is successful, the open function also makes an Access 
date and time stamp for the opened file when the following conditions are satisfied: 
the referenced drive has a directory label that requests Access date and time stamp- 
ing, and the FCB extent number field is zero. 

Upon return, the Open File function returns a directory code in register A widi the 
value OOH if the open was successful, or FFH, 255 decimal, if the file was not found. 
Register H is set to zero in both of these cases. If a physical or extended error was 
encountered, the Open File function performs different actions depending on the 
BDOS error mode (see Function 45). If the BDOS error mode is in the default mode, 
a message identifying the error is displayed at the console and the program is termi- 
nated. Otherwise, the Open File function returns to the calling program with register 
A set to OFFH, and register H set to one of the following physical or extended error 
codes: 

01 : Disk I/O Error 

04 : Invalid drive error 

07 : File password error 

09 : ? in the FCB filename or filetype field 



m DiCrTAL RESEARCH* 



3 BDOS Calls: Function 16 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 16 


CLOSE FILE 


Entry Parameters; 

Registers C: 

DE: 

Returned Value: 
Registers A: 
H: 


lOH 

FCB Address 

Director)^ Code 

Physical or Extended Error 



The Close File function performs the inverse of the Open File function. The calling 
program passes the address of an FCB in register pair DE. The referenced FCB must 
have been previously activated by a successful Open or Make (unction call (see 
Functions 15 and 22). Interface attribute f5' specifies how the file is to be closed as 
shown below: 

f5' = - Permanent close (default mode) 
15' = 1 - Partial close 



A permanent close operation indicates thai the program has completed file operations 
on the file. A partial close operation updates the directory, but indicates that the file 
is to be maintained in the open state. 

If the referenced FCB contains new information because of write operations to the 
FCB, the close function permanently records the new information in the referenced 
disk direaory. Note that the FCB does not contain new information, and the direc- 
tory update step is bypassed if only read or update operations have been made to the 
referenced FCB. 



El DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 16 

Upon return, the close function returns a directory code in register A with the 
value OOH if the close was successful, or FFH, 255 Decimal, if the file was not found. 
Register H is set to zero in both of these cases. If a physical or extended error is 
encountered, the close function performs different actions depending on the BDOS 
error mode (see Function 45). If the BDOS error mode is in the default mode, a 
message identifying the error is displayed at the console, and the calling program is 
terminated. Otherwise, the close function returns to the calling program with register 
A set to OFFH and register H set to one of the following physical error codes: 

01 ; Disk I/O error 

02 : Read/only disk 
04 : Invalid drive error 



li DIGITAL RESEARCH- 



3 BDOS Calls: Function 17 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 17: SEARCH FOR FIRST 



Entry Parameters: 

Registers C: IIH 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical Error 



The Search For First function scans the directory for a match with the FCB addressed 
by register pair DE. Two types of searches can be performed. For standard searches, 
the calling program initializes bytes through 12 of the referenced FCB, with byte 
specifying the drive direaory to be searched, bytes 1 through 1 1 specifying the file or 
tiles to be searched for, and byte 12 specifying the extent. Usually byte 12 is set to 
zero. An ASCII question mark, 6i decimal, 3F hex, in any of the bytes 1 through 12 
matches all entries on the directory in the corresponding position. This facility, called 
ambiguous reference, can be used to search for multiple files on the directory. When 
called in the standard mode, the Search function scans for the first file entry in the 
specified directory that matches the FCB, and belongs to the current user number. 

The Search For First function also initializes the Search For Next function. After 
the Search funaion has located the first directory entry matching the referenced FCB, 
the Search For Next function can be called repeatedly to locate all remaining match- 
ing entries. In terms of execution sequence, however, the Search For Next call must 
either follow a Search For First or Search For Next call with no other intervening 
BDOS disk-related function calls. 

If byte of the referenced FCB is set to a question mark, the Search function 
ignores the remainder of the referenced FCB, and locates the first directory entry 
residing on the current default drive. All remaining directory entries can be located 
by making multiple Search For Next calls. This type of search operation is not 
usually made by application programs, but it does provide complete flexibility to 
scan all current directory values. Note that this type of search operation must be 
performed to access a drive's directory label (see Section 2.3.6). 



f- CP/M 3 Programmer's Guide 3 BDOS Calls: Function 17 

Upon return, the Search function returns a Directory Code in register A with the 

"~ value to 3 if the search is successful, or OFFH, 255 Decimal, if a matching directory 

I entry is not found. Register H is set to zero in both of these cases. For successful 

searches, the current DMA is also filled with the directory record containing the 

H» matching entry, and the relative starting position is A * 32 {that is, rotate the A 

register left 5 bits, or ADD A five times). Although it is not usually required for 

application programs, the directory information can be extracted from the buffer at 

this position. 

If the directory has been initialized for date and time stamping by INITDIR, then 

an SFCB resides in every fourth direaory entry, and successful Directory Codes are 

'^ restricted to the values to 2, For successful searches, if the matching direaory 

, ; record is an extent zero entry, and if an SFCB resides at offset 96 within the current 

DMA, contents of (DMA Address + 96) = 21H, the SFCB contains the date and 

,^ time stamp information, and password mode for the file. This information is located 

I at the relative starting position of 97 + (A * 10) within the current DMA in the 

' ' following format: 

^ - 3 : Create or Access Date and Time Stamp Field 

I ( 4 - 7 : Update Date and Time Stamp Field 

8 : Password Mode Field 

' I (Refer to Section 2.3.8 for more information on SFCBs.) 

If a physical error is encountered, the Search function performs different actions 

I I depending on the BDOS error mode (see Function 45). If the BDOS error mode is in 

' the default mode, a message identifying the error is displayed at the console, and the 

calling program is terminated. Otherwise, the Search Unction returns to the calling 

■^ program with register A set to OFFH, and register H set to one of the following 

, I physical error codes: 

_ 01 : Disk I/O error 

i 1 04 : Invalid drive error 



m DIGITAL RESEARCH' 



3 BDOS Calls: Funciion 18 



CP/M 3 Programmer's Guide ** 



BDOS FUNCTION 1 8 : SEARCH FOR NEXT 



Entry Parameters: 

Register C: 12H 

Returned Value: 

Registers A: Directory Code 
H: Physical Error 



The Search For Next hinction is identical to the Search For First function, except 
that the directory scan continues from the last entry that was matched. Funaion 18 
returns a Directory code in register A, analogous to Function 17. 

Note: in execution sequence, a Funaion 18 call must follow either a Function 17 or 
another Function 18 call with no other intervening BDOS disk-related function calls. 



- EDICrrAL RESEARCH" 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 19 



BDOS FUNCTION 19: DELETE FILE 



Entry Parameters: 

Registers C: 13H 

DE: FCB Address 

Returned Value: 

Registers A: Direaory Code 

H: Extended or Physical Error 



The Delete File function removes files or XFCBs that match the FCB addressed in 
register pair DE. The filename and filetype can contain ambiguous references, that is, 
question marks in bytes fl through t3, but the dr byte cannot be ambiguous, as it 
can in the Search and Search Next functions. Interface attribute i5' specifies the type 
of delete operation that is performed. 

f5' = - Standard Delete (default mode) 
f5' = 1 - Delete only XFCBs 

If any of the files that the referenced FCB specify are password protected, the correct 
password must be placed in the first eight bytes of the current DMA buffer, or have 
been previously established as the default password [see Function 106). 

For standard delete operations, the Delete funaion removes all directory entries 
belonging to files that match the referenced FCB. All disk directory and data space 
owned by the deleted files is returned to free space, and becomes available for allo- 
cation to other files. Directory XFCBs that were owned by the deleted files are also 
removed from the direaory. If interface attribute tS' of the FCB is set to 1, Function 
19 deletes only the directory XFCBs that match the referenced FCB. 

Note: if any of the files that match the input FCB specification fail the password 
check, or are Read-Only, then the Delete function does not delete any files or XFCBs. 
This applies to both types of delete operations. 



L»l DIGITAL RESEARCH" 



3 BDOS Calls: Function 19 CP/M 3 Programmer's Guide « 

In nonbanked systems, file passwords and XFCBs are not supported. Thus, if the 
Delete function is called with interface anribute iS' set to true, the Delete funaion "~ 
performs no action but returns with register A set to zero. 

Upon return, the Delete funaion returns a Directory Code in register A with the — 
value if the delete is successful, or OFFH, 255 Decimal, if no file that matches the 
referenced FCB is found. Register H is set to zero in both of these cases. If a physical, 
or extended error is encountered, the Delete function performs different aaions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is 
the default mode, a message identifying the error is displayed at the console and the 
caUing program is terminated. Otherwise, the Delete function returns to the calling 
program with register A set to OFFH and register H set to one of the following ~ 
physical or extended error codes: J \ 

01 ; Disk I/O error „ 

02 : Read-Only disk I i 

03 : Read-Only file ' ' 

04 : Invalid drive error 

07 : File password error ^ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 20 



BDOS FUNCTION 20: READ SEQUENTIAL 



Entry Parameters: 

Registers C: 14H 

DE: FCB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Read Sequential function reads the next 1 to 128 128-byte records from a file 
into memory beginning at the current DMA address. The BDOS Multi-Sector Count 
(see Function 44} determines the number of records to be read. The default is one 
record. The FCB addressed by register pair DE must have been previously activated 
by an Open or Make function call. 

Function 20 reads each record from byte cr of the extent, then automatically 
increments the cr field to the next record position. If the cr field overflows, then the 
function automatically opens the next logical extent and resets the cr field to in 
preparation for the next read operation. The calling program must set the cr field to 
following the Open call if the intent is to read sequentially from the beginning of 
the file. 



Upon return, the Read Sequential function sets register A to zero if the read oper- 
ation is successful. Otherwise, register A contains an error code identifying the error 
as shown below: 

01 : Reading unwritten data (end-of-file) 

09 ; Invalid FCB 

10 : Media change occurred 

255 : Physical Error; refer to register H 



11 DIGITAL RESEARCH' 



3 BDOS Calls: Function 20 CP/M 3 Programmer's Guide 

Error Code 01 is returned if no data exists at the next record position of the file. 
Usually, the no data situation is encountered at the end of a file. However, it can 
also occur if an attempt is made to read a data block that has not been previously 
written, or an extent which has not been created. These situations are usually restricted 
to files created or appended with the BDOS random write functions (see Functions 
34 and 40). 

Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call that 



Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is acrivated by a BDOS Open, or Make Call. 

Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is Return Error mode, or Return and Display Error mode (see Function 45), If 
the error mode is the default mode, a message idenrifying the physical error is dis- 
played at the console, and the calling program is terminated. When a physical error 
is returned to the calling program, register H contains one of the following error 
codes: 

01 : Disk I/O error 
04 : Invalid drive error 

On all error returns except for physical error returns, A = 255, Function 20 sets 
register H to the number of records successfully read before the error is encountered. 
This value can range from to 127 depending on the current BDOS Multi-Sector 
Count. It is always set to zero when the Multi-Seaor Count is equal to one. 



■"DIGITAL RESEARCH" 



" CP/M 3 Programmer's Guide 



BDOS FUNCTION 21; WRITE SEQUENTIAL 



Entry Parameters: 

Registers C: 15H 

DE: FCB Address 

Returned Value: 

Registers A; Error Code 

H: Physical Error 



The Write Sequential function writes 1 to 128 128-byte data records, beginning at 
the current DMA address into the file named by the FCB addressed in register pair 
DE, The BDOS Multi-Sector Count (see Function 44) determines the number of 128 
byte records that are written. The default is one record. The referenced FCB must 
have been previously activated by a BDOS Open or Make function call. 

Function 21 places the record into the file at the position indicated by the cr byte 
of the FCB, and then automatically increments the cr byte to the next record posi- 
tion. If the cr field overflows, the function automatically opens, or creates the next 
logical extent, and resets the cr field to in preparation for the next write operation. 
If Function 21 is used to write to an existing file, then the newly written records 
overlay those already existing in the file. The calling program must set the cr field to 
following an Open or Make call if the intent is to write sequentially from the 
beginning of the file. 

Function 21 makes an Update date and time for the file if the following conditions 
are satisfied: the referenced drive has a directory label that requests date and time 
stamping, and the file has not already been stamped for update by a previous Make 
or Write function call. 



'? DIGITAL RESEARCH* 



3 BDOS Calls: Function 21 CP/M 3 Programmer's Guide P 

Upon return, the Write Sequential function sets register A to zero if the write ^ 

operation is successful. Otherwise, register A contains an error code identifying the , 
error as shown below: 

01 : No available directory space ^ 

02 : No available data block , \ , 

09 : Invahd FCB 

10 : Media change occurred *« 
255 : Physical Error : refer to register H • ' 

Error Code 01 is returned when the write funaion attempts to create a new extent 
that requires a new directory entry, and no available directory entries exist on the 
selected disk drive. 

Error Code 02 is returned when the write command attempts to allocate a new — i 
data block to the file, and no unallocated data blocks exist on the selected disk drive. 

Error Code 09 is returned if the FCB is invalidated by a previous BDOS close call _ 

that returns an error, ' ] 

Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is aaivated by a BDOS Open or Make call. p 



IIDIGITAL RESEARCH' 



-' CP/M 3 Programmers Guide 3 BDOS Calls: Function 21 

Error Code 255 is returned if a physical error is encountered and the BDOS error 
" mode is Return Error mode, or Return and Display Error mode (see Function 45). If 

the error mode is the default mode, a message identifying the physical error is dis- 
played at the console, and the calling program is terminated. When a physical error 
.— I is returned to the calling program, register H contains one of the following error 

codes: 

01 : Disk yO error 
" 02 : Read-Only disk 

03 ; Read-Only file or 

File open from user when 
^ the current user number is non-zero or 

I File password protected in Write mode 

04 : Invalid drive error 

'-I 

I I On all error returns, except for physical error returns, A = 255, Funaion 21 sets 

register H to the number of records successfully written before the error was encoun- 
tered. This value can range from to 127 depending on the current BDOS Multi- 

Tj Sector Count. It is always set to zero when the Multi-Sector Count is set to one. 



Li^ DIGITAL RESEARCH* 



3 BDOS Calls: Function 22 



CP/M 3 Programmer's Guide "^ 



BDOS FUNCTION 22: MAKE FILE 



Entry Parameters: 

Registers C: 16H 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended Error 



The Make File function creates a new directory entry for a file under the current 
user number. It also creates an XFCB for the file if the referenced drive has a direc- 
tory label that enables password protection on the drive, and the calling program 
assigns a password to the file. 

The calling program passes the address of the FCB in register pair DE, with byte 
of the FCB specifying the drive, bytes 1 through 11 specifying the filename and •" 

filetype, and byte 12 set to the extent number. Usually, byte 12 is set to zero. Byte 
32 of the FCB, the cr field, must be initialized to zero, before or after the Make call, 
if the intent is to write sequentially from the beginning of the file. ^ 

Interface attribute f6' specifies whether a password is to be assigned to the created 

file. 

n 

f6' = - Do not assign password (default) ' ' 

f6' = 1 - Assign password to created file 

When attribute f6' is set to 1, the calling program must place the password in the 
first 8 bytes of the current DMA buffer, and set byte 9 of the DMA buffer to the 
password mode (see Function 102). Note that the Make function only interrogates 
interface attribute f6' if passwords are activated on the referenced drive. In non- i 

banked systems, file passwords are not supported, and attribute f6' is never interrogated. 

The Make function returns with an error if the referenced FCB names a file that "^ 

currently exists in the directory under the current user number. | 



||J DIGITAL RESEARCH- 



CP/M 3 Programmer's Guide 3 BDOS Calls: Funciion 22 

If the Make function is successful, it activates the referenced FCB for fiJe opera- 
tions by opening the FCB, and initializes both the directory entry and the referenced 
FCB to an empty file. It also initializes all file attributes to zero. In addition. Function 
22 makes a Creation date and time stamp for the file if the following conditions are 
satisfied: the referenced drive has a directory label that requests Creation date and 
time stamping and the FCB extent number field is equal to zero. Funaion 22 also 
makes an Update stamp if the directory label requests update stamping and the FCB 
extent field is equal to zero. 

If the referenced drive contains a directory label that enables password protection, 
and if interface attribute f6' has been set to 1, the Make function creates an XFCB 
for the tile. In addition, Function 22 also assigns the password, and password mode 
placed in the first nine bytes of the DMA, to the XFCB. 

Upon return, the Make function returns a directory code in register A with the 
value if the make operation is successful, or OFFH, 255 decimal, if no directory 
space is available. Register H is set to zero in both of these cases. If a physical or 
extended error is encountered, the Make funaion performs different actions depend- 
ing on the BDOS error mode (see Function 45). If the BDOS error mode is the 
default mode, a message identifying the error is displayed at the console, and the 
calling program is terminated. Othervwise, the Make function returns to the calling 
program with register A set to OFFH, and register H set to one of the following 
physical or extended error codes; 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Invalid drive error 

08 : File already exists 

09 : ? in filename or filetype field 



Ml DIGITAL RESEARCH" 



3 BDOS Calls: Function 23 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 23: RENAME FILE 



Entry Parameters: 

Registers C: 17H 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended Error 



The Rename function uses the FCB, addressed by register pair DE, to change all 
direaory entries of the file specified by the filename in the first 16 bytes of the FCB 
to the filename in the second 16 bytes. If the file specified by the first filename is 
password protected, the correct password must be placed in the first eight bytes of 
the current DMA buffer, or have been previously established as the default password 
(see Funaion 106). The calling program must also ensure that the filenames specified 
in the FCB are valid and unambiguous, and that the new filename does not already 
exist on the drive. Function 23 uses the dr code at byte of the FCB to select the 
drive. The drive code at byte 16 of the FCB is ignored. 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 23 



Upon return, the Rename function returns a Directory Code in register A with the 
value if the rename is successful, or OFFH, 255 Decimal, if the file named by the 
first filename in the FCB is not found. Register H is set to zero in both of these cases. 
If a physical or extended etror is encountered, the Rename function performs differ- 
ent actions depending on the BDOS error mode (see Function 45). If the BDOS error 
mode is the default mode, a message identifying the error is displayed at the console 
and the program is terminated. Otherwise, the Rename function returns to the calling 
program with register A set to OFFH and register H set to one of the following 
physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 

03 ; Read-Only file 

04 ; Invalid drive error 

07 ; File password error 

08 : File already exists 

09 : ? in filename or filetype lield 



m DIGITAL RESEARCH* 



3 BDOS Calls: Function 24 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 24: RETURN LOGIN VECTOR 



Entry Parameters: 

Register C: 18H 



Returned Value: 

Register FiL: Login Vector 



n 
n 



Funaion 24 returns the login vector in register pair HL. The login vector is a 16- 
bit value with the least significant bit of L corresponding to drive A, and the high- 
order bit of H corresponding to the 16th drive, labelled P. A bit indicates that the 
drive is not on-line, while a 1 bit indicates the drive is active. A drive is made active 
by either an exphcit BDOS Select Disk call, number 14, or an implicit seteaion when 
a BDOS file operation specifies a non-zero dr byte in the FCB. Funaion 24 maintains 
compatibilty with earlier releases since registers A and L contain the same values 
upon return. 



n 
n 



-1 CP/M 3 Programmer's Guide 



3 BDOS Calls: Fun. 



BDOS FUNCTION 25: RETURN CURRENT DISK 



Entry Parameters: 

Register C: 19H 



Returned Value: 

Register A: Current Disk 



Function 25 returns the currently selected default disk number in register A. The 
disk numbers range from through 15 corresponding to drives A through P. 



HI DIGITAL fttSEARCH' 



3 BDOS Calk: Funciion 26 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 26: SET DMA ADDRESS 



Entry Parameters: 

Registers C: lAH 

DE: DMA Address 



DMA is an acronym for Direct Memory Address, which is often used in connec- 
tion with disk controllers that directly access the memory of the computer to transfer 
data to and from the disk subsystem. Under CP/M 3, the current DMA is usually 
defined as the buffer in memory where a record resides before a disk write, and after 
a disk read operation. If the BDOS Multi-Sector Count is equal to one (see Function 
44), the size of the buffer is 128 bytes. However, if the BDOS Multi-Seaor Count is 
greater than one, the size of the buffer must equal N * 128, where N equals the 
Multi-Sector Count. 



Some BDOS functions also use the current DMA to pass parameters, and to return 
values. For example, BDOS functions that check and assign file passwords require 
that the password be placed in the current DMA. As another example. Function 46, 
Get Disk Free Space, returns its results in the first 3 bytes of the current DMA. When 
the current DMA is used in this context, the size of the buffer in memory is deter- 
mined by the specific requirements of the called function. 

When a transient program is initiated by the CCP, its DMA address is set to 
0080H. The BDOS Reset Disk System funaion, Funaion 13, also sets the DMA 
address to 0080H, The Set DMA function can change this default value to another 
memory address. The DMA address is set to the value passed in the register pair DE. 
The DMA address remains at this value until it is changed by another Set DMA 
Address, or Reset Disk System call. 



M DIGITAL RESEARCH- 



3 BDOS Calls: 



1 

n 
n 

n 

1 



BDOS FUNCTION 27: GET ADDR(ALLOC) 



Entry Parameters: 

Register C: IBH 



Returned Value: 

Register HL: ALLOC Address 



CP/M 3 maintains an allocation vector in main memory for each active disk drive. 
Some programs use the information provided by the allocation vector to determine 
the amount of free data space on a drive. Note, however, that the allocation infor- 
mation might be inaccurate if the drive has been marked Read-Only. 



Function 27 returns in register pair HL, the base address of the allocation vector 
for the currently selected drive. If a physical error is encountered when the BDOS 
error mode is one of the return modes (see Function 45), Function 27 returns the 
value OFFFFH in the register pair HL. 

In banked CP/M 3 systems, the allocation veaor can be placed in bank zero. In 
this case, a transient program cannot access the allocation vector. However, the 
BDOS funaion. Get Disk Free Space [Function 46), can be used to directly return 
the number of free 128-byte records on a drive. The CP/M 3 utilities that display a 
drive's free space, DIR and SHOW, use Function 46 for that purpose. 



•i' DICITAL RtSEARCH' 



3 BDOS Calk: Function 28 



BDOS FUNCTION 28: WRITE PROTECT DISK 



CP/M 3 Programmer's Guide "^ 

n 



Entry Parameters: 

Register C: ICH 



The Write Protect Disk function provides temporary write protection for the cur- 
rently selected disk by marking the drive as Read-Only. No program can write to a 
disk that is in the Read-Only state. A drive reset operation must be performed for a 
Read-Only drive to restore it to the Read-Write state (see Funaions 13 and 37). 



llDiGJTAI. RESEARCH- 



CP/M 3 Programmer's Guide 



3 BDOS Calls; Function 29 



BDOS FUNCTION 29: GET READ-ONLY VECTOR 



Entry Parameters: 

Register C: IDH 



Returned Value: 

Register HL: R/O Vector Value 



Function 29 returns a bit vector in register pair HL that indicates which drives 
have the temporary Read-Only bit set. The Read-Only bit can be set only by a BDOS 
Write Protea Disk call. 

The format of the bit veaor is analagous to that of the login vector returned by 
Function 24. The least significant bit corresponds to drive A, while the most signifi- 
cant bit corresponds to drive P. 



3 BDOS Calls: Function 30 



BDOS FUNCTION 30: SET FILE ATTRIBUTES 



Entry Parameters: 

Registers C: lEH 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Physical or Extended error 



By calling the Set File Attributes function, a program can modify a file's attributes 
and set its last record byte count. Other BDOS functions can be called to interrogate 
these file parameters, but only Function 30 can change them. The file attributes that 
can be set or reset by Funaion 30 are fl' through f4', Read-Only, tl'. System, t2', 
and Archive, t3'. The register pair DE addresses an FCB containing a filename with 
the appropriate attributes set or reset. The caHing program must ensure that it does 
not specify an ambiguous filename. In addition, if the specified file is password pro- 
teaed, the correa password must be placed in the first eight bytes of the current 
DMA buffer or have been previously established as the default password (see Func- 
tion 106}. 

Interface attribute f6' specifies whether the last record byte count of the specified 
file is to be set: 



■ - Do not set byte count {default mode) 

■ 1 - Set byte count 



If interface attribute f6' is set, the calling program must set the cr field of the refer- 
enced FCB to the byte count value. A program can access a file's byte count value 
with the BDOS Open, Search, or Search Next functions. 

Function 30 searches the referenced directory for entries belonging to the current 
user number that matches the FCB specified name and type fields. The function then 
updates the direaory to contain the selected indicators, and if interface attribute f6' 
is set, the specified byte count value. Note that the last record byte count is main- 
tained in byte 13 of a file's directory FCBs. 



■ : DIGITAL RESEARCH' 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 30 

File attributes tl', t2', and t3' are defined by CP/M 3. (They are described in 
Seaion 2.3.4,) Attributes iV through H' are not presently used, but can be useful for 
apphcation programs, because they are not involved in the matching program used 
by the BDOS during Open File and Close File operations. Indicators f5' through f8' 
are reserved for use as interface attributes. 

Upon return. Function 30 returns a Directory Code in re^ster A with the value 
if the function is successful, or OFFH, 255 Decimal, if the file specified by the refer- 
enced FCB is not found. Register H is set to zero in both of these cases. If a physical 
or extended error is encountered, the Set File Attributes function performs different 
actions depending on the BDOS error mode (see Function 45). If the BDOS error 
mode is the default mode, a message identifying the error is displayed at the console, 
and the program is terminated. Otherwise, Function 30 returns to the calhng pro- 
gram with register A set to OFFH, and register H set to one of the following physical 
or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Select error 

07 : File password error 

09 ; ? in filename or filetype field 



M DIGITAL RESEARCH- 



3 BDOS Calls: Function 31 



CP/M 3 Programmer's Guide ■" 



BDOS FUNCTION 31: GET ADDR(DPB PARMS) 



Entry Parameters: 

Register C: IFH 



Returned Value: 

Register HL: DPB Address 



Function 31 returns in register pair HL the address of the BIOS-resident Disk 
Parameter Block, DPB, for the currendy selected drive. (Refer to the CP/M Plus 
(CPIM Version 3) Operating System System Guide for the format of the DPB). The 
calling program can use this address to extraa the disk parameter values. 

If a physical error is encountered when the BDOS error mode is one of the return 
modes (see Function 45), Function 31 returns the value OFFFFH in the register pair 
HL. 



■-DIGITAL RESEARCH- 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 32 



BDOS FUNCTION 32; SET/GET USER CODE 



Entry Parameters; 

Registers C: 20H 

E: OFFH (get) or User Code [set) 

Returned Value: 

Register A: Current Code or 
(no value) 



A program can change, or interrogate the currently active user number by calling 
Function 32, If register E = OFFH, then the value of the current user number is 
returned in register A, where the value is in the range of to 15. If register E is not 
OFFH, then the current user number is changed to the value of E, modulo 16. 



':'DICirftL RESEARCH- 



3 BDOS Calls: Function 33 



BDOS FUNCTION 33: READ RANDOM 



Entry Parameters: 

Registers C: 21H 

DE: FOB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Read Random function is similar to the Read Sequential function except that 
the read operation lakes place at a particular random record number, selected by the 
24-bit value constructed from the three byte, rO, rl, r2, field beginning at position 
33 of the FCB. Note that the sequence of 24 bits is stored with the least significant 
byte first, rO, the middle byte next, rl, and the high byte last, r2. The random record 
number can range from to 262,143. This corresponds to a maximum value of 3 in 
byte r2. 

To read a file with Function 33, the calling program must first open the base 
extent, extent 0, This ensures that the FCB is properly initialized for subsequent 
random access operations. The base extent may or may not contain any allocated 
data. Function 33 reads the record specified by the random record field into the 
current DMA address. The function automatically sets the logical extent and current 
record values, but unlike the Read Sequential function, it does not advance the 
current record number. Thus, a subsequent Read Random call rereads the same 
record. After a random read operation, a file can be accessed sequentially, starting 
from the current randomly accessed position. However, the last randomly accessed 
record is reread or rewritten when switching from random to sequential mode. 

If the BDOS Multi-Sector Count is greater than one (see Function 44), the Read 
Random function reads multiple consecutive records into memory beginning at the 
current DMA. The rO, rl, and r2 field of the FCB is automatically incremented to 
read each record. However, the FCBs random record number is restored to the first 
record's value upon return to the calling program. 



^DICnAL RESEARCH" 



" CP/M 3 Programmer's Guide 3 BDOS Calls: Function 33 

Upon return, the Read Random function sets register A to zero if the read opera- 
n tion was successful. Otherwise, register A contains one of the following error codes: 

01 : Reading unwritten data (end-of-file) 
■^ 03 : Cannot close current extent 

I 04 : Seek to unwritten extent 

06 : Random record number out of range 

10 : Media change occurred 
I 255 : Physical Error ; refer to register H 

Error Code 01 is returned if no data exists at the next record position of the file. 

■^ Usually, the no data situation is encountered at the end of a file. However, it can 

I also occur if an attempt is made to read a data block that has not been previously 



Error Code 03 is returned when the Read Random function cannot close the 
current extent prior to moving to a new extent. 

Error Code 04 is returned when a read random operation accesses an extent that 
has not been created. 

Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 



Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is activated by a BDOS Open or Make Call. 

Error Code 255 is returned if a physical error is encountered, and the BDOS error 
mode is one of the return modes {see Function 45). If the error mode is the default 
mode, a message identifying the physical error is displayed at the console, and the 
calling program is terminated. When a physical error is returned to the calling pro- 
gram, register H contains one of the following error codes: 

01 : Disk I/O error 
04 : Invalid drive error 

On all error returns except for physical errors, A = 255, the Read Random 
function sets register H to the number of records successfully read before the error is 
encountered. This value can range from to 127 depending on the current BDOS 
Multi-Sector Count, It is always set to zero when the Multi-Sector Count is equal to 



SiDICiTAL RESEARCH ' 



3 BDOS Calls: Function 34 



CP/M 3 Programmer'!) Guide 



BDOS FUNCTION 34; WRITE RANDOM 


Entry Parameters: 

Registers C: 

DE: 

Returned Value: 
Registers A: 
H: 


22H 

FCB Address 

Error Code 
Physical Error 



The Write Random function is analogous to the Read Random function, except 
that data is written to the disk from the current DMA address. If the disk extent or 
data block where the data is to be written is not already allocated, the BDOS auto- 
matically performs the allocation before the write operation continues. 

To write to a file using the Write Random funaion, the calling program must first 
open the base extent, extent 0. This ensures that the FCB is properly initialized for 
subsequent random access operations. If the file is empty, the calling program must 
create the base extent with the Make File function before calling Function 34. The 
base extent might or might not contain any allocated data, but it does record the file 
in the directory, so that the file can be displayed by the DIR utility. 

The Write Random function sets the logical extent and current record positions to 
correspond with the random record being written, but does not change the random 
record number. Thus, sequential read or write operations can follow a random write, 
with the current record being reread or rewritten as the calling program switches 
from random to sequential mode. 

Function 34 makes an Update date and time stamp for the file if the following 
conditions are satisfied: the referenced drive has a direaory label that requests Update 
date and time stamping if the file has not already been stamped for update by a 
previous BDOS Make or Write call. 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 34 

If the BDOS Multi-Sector Count is greater than one [see Function 44), the Write 
Random function reads multiple consecutive records into memory beginning at the 
current DMA. The rO, rl, and r2 field of the FCB is automatically incremented to 
write each record. However, the FCB's random record number is restored to the first 
record's value when it returns to the calling program. Upon return, the Write Ran- 
dom function sets register A to zero if the write operation is successful. Otherwise, 
register A contains one of the following error codes: 

02 : No available data block 

03 : Cannot Close current extent 

05 : No available directory space 

06 : Random record number out of range 
10 ; Media change occurred 

255 : Physical Error : refer to register H 

Error Code 02 is returned when the write command attempts to allocate a new 
data block to the file and no unallocated data blocks exist on the selected disk drive. 

Error Code 03 is returned when the Write Random function cannot close the 
current extent prior to moving to a new extent. 

Error Code 05 is returned when the write function attempts to create a new extent 
that requires a new directory entry and no available directory entries exist on the 
selected disk drive. 

Error Code 06 is returned when byte 35, r2, of the referenced FCB is greater than 



Error Code 10 is returned if a media change occurs on the drive after the refer- 
enced FCB is activated by a BDOS Open or Make Call. 



m DIGITAL RESEARCH 1 



3 BDOS CalU: Function 34 CP/M 3 Programmer's Guide 

Error Code 255 is returned if a physical error is encountered and the BDOS error 
mode is one of the return modes (see Function 45), If the error mode is the default 
mode, a message identifying the physical error is displayed at the console, and the 
calling program is terminated. When a physical error is returned to the calling pro- 
gram, it is identified by register H as shown below: 

01 ; Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file or 

File open from user when the current user number is nonzero or 
File password protected in Write mode 

04 : Invalid drive error 

On all error returns, except for physical errors, A = 255, the Write Random 
function sets register H to the number of records successfully written before the error 
is encountered. This value can range from to 127 depending on the current BDOS 
Multi-Sector Count. It is always set to zero when the Multi-Sector Count is equal to 



- m DIGITAL RESEARCH' 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 35 



BDOS FUNCTION 35: COMPUTE FILE SIZE 



Entry Parameters: 

Registers C: 23H 

DE: FCB Address 

Returned Value: 

Registers A: Error Flag 

H: Physical or Extended error 

Random Record Field Set 



The Compute File Size function determines the virtual file size, which is, in effect, 
the address of the record immediately following the end of the file. The virtual size 
of a file corresponds to the physical size if the file is written sequentially. If the file is 
wrinen in random mode, gaps might exist in the allocation, and the file might con- 
tain fewer records than the indicated size. For example, if a single record with record 
number 262,143, the CP/M 3 maximum is written to a file using the Write Random 
function, then the virtual size of the file is 262,144 records even though only 1 data 
block is actually allocated. 

To compute file size, the calling program passes in register pair DE the address of 
an FCB in random mode format, bytes rO, rl and r2 present. Note that the FCB 
must contain an unambiguous filename and filetype. Function 35 sets the random 
record field of the FCB to the random record number + 1 of the last record in the 
file. If the r2 byte is set to 04, then the file contains the maximum record count 
262,144. 

A program can append data to the end of an existing file by calling Function 35 to 
set the random record position to the end of file, and then performing a sequence of 
random writes starting at the preset record address. 

Note: the BDOS does not require that the file be open to use Function 35. However, 
if the file has been written to, it must be closed before calling Function 35. Other- 
wise, an incorrect file size might be returned. 



3 BDOS Calls: Function 35 

Upon return, Function 35 returns a zero in register A if the file specified by the 
referenced FCB is found, or an OFFH in register A if the file is not found. Register H 
is set to zero in both of these cases. If a physical error is encountered. Function 35 
performs different actions depending on the BDOS error mode (see Function 45). 
If the BDOS error mode is the default mode, a message identifying the error is 
displayed at the console and the program is terminated. Otherwise, Function 35 
returns to the calling program with register A set to OFFH, and register H set to one 
of the following physical errors: 

01 : Disk I/O error 
04 : Invalid drive error 



-HDICITAL RESEARCH' 



. n 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Fun* 



BDOS FUNCTION 36: SET RANDOM RECORD 



Entry Parameters: 

Registers C: 24H 

DE: FCB Address 

Returned Value: Random Record Field Set 



The Set Random Record function returns the random record number of the next 
record to be accessed from a file that has been read or written sequentially to a 
particular point. This value is returned in the random record field, bytes rO, rl, and 
r2, of the FCB addressed by the register pair DE. Function 36 can be useful in two 
ways. 

First, it is often necessary to initially read and scan a sequential file to extract the 
positions of various key fields. As each key is encountered, Function 36 is called to 
compute the random record position for the data corresponding to this key. If the 
data unit size is 128 bytes, the resulting record number minus one is placed into a 
table with the key for later retrieval. After scanning the entire file and tabularizing 
the keys and their record numbers, you can move directly to a particular record by 
performing a random read using the corresponding random record number that you 
saved earlier. The scheme is easily generalized when variable record lengths are involved, 
because the program need only store the buffer-relative byte position along with the 
key and record number to find the exact starring position of the keyed data at a later 
rime, 

A second use of Function 36 occurs when switching from a sequential read or 
write over to random read or write. A tile is sequentially accessed to a particular 
point in the file, then Function 36 is called to set the record number, and subsequent 
random read and write operations continue from the next record in the file. 



Ml DIGITAL RESEARCH' 



3 BDOS Calls: Function 37 



BDOS FUNCTION 37: RESET DRIVE 



Entry Parameters: 

Registers C: 25H 

DE: Drive Vector 

Returned Value: 

Register A: OOH 



The Reset Drive funaion programmatically restores specified drives to the reset 
state. A reset drive is not logged-in and is in Read- Write status. The passed parame- 
ter in register pair DE is a 16-bit veaor of drives to be reset, where the least signifi- 
cant bit corresponds to the first drive A, and the high-order bit corresponds to the 
sixteenth drive, labelled P. Bit values of 1 indicate that the specified drive is to be 



n 

r 



ffl DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 38 



BDOS FUNCTION 38: ACCESS DRIVE 



Entry Parameters: 

Register C: 26H 



This is an MP/M function that is not supported under CP/M 3, If called, the file 
n system returns a zero in register A indicating that the access request is successful. 



»:i 



H DIGITAL RESEARCH"* 



3 BDOS Calls: Function 39 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 39: FREE DRIVE 



Entry Parameters: 

Register C: 27H 



This is an MP/M function that is not supported under CP/M 3. If called, the file 
system returns a zero in register A indicating that the free request is successful. 



- 51 DIGITAL RESEARCH' 



CP/M 3 Programm 



3 BDOS Calls: Function 40 



BDOS FUNCTION 40: WRITE RANDOM WITH 
ZERO HLL 



Entry Parameters: 

Registers C: 28H 

DE: FOB address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Write Random With Zero Fill function is identical to the Write Random 
function (Function 34) with the exception that a previously unallocated data block is 
filled with zeros before the record is written. If this function has been used to create 
a file, records accessed by a read random operation that contain all zeros identify 
unwritten random record numbers. Unwritten random records in aUocated data blocks 
of files created using the Write Random function (Function 34) contain uninitialized 
data. 



El DIGfTAL RESEARCH- 



3 BDOS Calls: Function 41 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 41: TEST AND WRITE RECORD 



Entry Parameters; 

Registers C; 29H 

DE: FCB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



The Test and Write Record function is an MP/M 11'" function that is not sup- 
ported under CP/M 3. If called, Function 41 returns with register A set to OFFFl and 
register H set to zero. 



- m DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 42: LOCK RECORD 



Entry Parameters: 

Registers C: 2AH 

DE: FCB Address 

Returned Value: 

Register A: OOH 



The Lock Record function is an MP/M II function that is supported under CP/M 3 
only to provide compatibility between CP/M 3 and MP/M. It is intended for use in 
situations where more than one running program has Read-Write access to a com- 
mon file. Because CP/M 3 is a single-user operating system in which only one pro- 
gram can run at a time, this situation cannot occur. Thus, under CP/M 3, Function 
42 performs no action except to return the value OOH in register A indicating that 
the record lock operation is successful. 



19 DIGITAL RESEARCH "' 



3 BDOS Calls; Fun. 



CP/M 3 Progr; 



BDOS FUNCTION 43; UNLOCK RECORD 



Entry Parameters: 

Registers C; 2BH 

DE: FCB Address 

Returned Value: 

Register A: OOH 



The Unlock Record function is an MP/M II function that is supported under 
CP/M 3 only to provide compatibility between CP/M 3 and MP/M, It is intended for 
use in situations where more than one running program has Read-Write access to a 
common file. Because CP/M 3 is a single-user operating system in which only one 
program can run at a time, this situation cannot occur. Thus, under CP/M 3, Func- 
tion 43 performs no action except to return the value OOH in register A indicating 
that the record unlock operation is successful. 



i'DIGITAL RESEARCH' 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Funciion 44 



BDOS FUNCTION 44: SET MULTI-SECTOR COUNT 



Entry Parameters: 

Registers C: 2CH 

E: Number of Sectors 

Returned Value: 

Register A: Return Code 



The Set Multi-Sector Count function provides logical record blocking under 
CP/M 3. It enables a program to read and write from 1 to 128 records of 128 bytes 
at a time during subsequent BDOS Read and Write functions. 

Function 44 sets the Multi-Sector Count value for the calling program to the value 
passed in register E. Once set, the specified Multi-Sector Count remains in effect until 
the calling program makes another Set Multi-Sector Count function call and changes 
the value. Note that the CCP sets the Multi-Sector Count to one when it initiates a 
transient program. 

The Multi-Sector Count affeas BDOS error reporting for the BDOS Read and 
Write functions. If an error interrupts these functions when the Multi-Seaor is greater 
than one, they return the number of records successfully read or written in register 
H for all errors except for physical errors (A = 255). 

Upon return, register A is set to zero if the specified value is in the range of 1 to 
128. Otherwise, register A is set to OFFH. 



"i DIGITAL RESEARCH" 



3 BDOS Calls; Function 45 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 45: SET BDOS ERROR MODE 



Entry Parameters: 

Registers C: 2DH 

E: BDOS Error Mode 

Returned Value: None 



Function 45 sets the BDOS error mode for the calling program to the mode speci- 
fied in register E. If register E is set to OFFH, 255 decimal, the error mode is set to 
Return Error mode. If register E is set to OFEH, 254 decimal, the error mode is set 
to Return and Display mode. If register E is set to any other value, the error mode is 
set to the default mode. 

The SET BDOS Error Mode function determines how physical and extended errors 
(see Section 2.2.13) are handled for a program. The Error Mode can exist in three 
modes: the default mode. Return Error mode, and Return and Display Error mode. 
In the default mode, the BDOS displays a system message at the console that identi- 
fies the error and terminates the calling program. In the return modes, the BDOS sets 
register A to OFFH, 255 decimal, places an error code that identifies the physical or 
extended error in register H and returns to the calling program. In Return and 
Display mode, the BDOS displays the system message before returning to the calling 
program. No system messages are displayed, however, when the BDOS is in Return 
Error mode. 



- m DrCITAI. RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 46 



BDOS FUNCTION 46: GET DISK FREE SPACE 



Entry Parameters: 

Registers C-. 2EH 
E; Drive 

Returned Value: First 3 bytes 

of current DMA 
buffer 
Registers A: Error Flag 

H: Physical Error 



The Get Disk Free Space function determines the number of free sectors, 128 byte 
records, on the specified drive. The calling program passes the drive number in 
register E, with for drive A, 1 for B, and so on, through 15 for drive P in a full 16- 
drive system. Function 46 returns a binary number in the first 3 bytes of the current 
DMA buffer. This number is returned in the following format: 



M 


fsl 


fs2 



Disk Free Space Field Format 

fsO = low byte 
fsl = middle byte 
fsl = high byte 



Note that the returned free space value might be 
marked Read-Only. 



if the drive has bet 



m DIGITAL RESEARCH™ 



3 BDOS Calls; Function 46 CP/M 3 Programmer's Guide 

Upon return, register A is set to zero if the funaion is successful. However, if the 
BDOS Error Mode is one of the return modes {see Function 45), and a physical error 
is encountered, register A is set to OFFH, 255 decimal, and register H is set to one of 
the following values: 

01 - Disk I/O error 
04 - Invalid drive error 



n 



CP/M 3 Programm 



3 BDOS Calls: Function 47 



BDOS FUNCTION 47: CHAIN TO PROGRAM 



Entry Parameters; 

Registers C: 2FH 

E: Chain Flag 



The Chain To Program function provides a means of chaining from one program 
to the next without operator intervention. The calling program must place a com- 
mand line terminated by a null byte, OOH, in the default DMA buffer. !f register E is 
set to OFFH, the CCP initializes the default drive and user number to the current 
program values when it passes control to the specified transient program. Otherwise, 
these parameters are set to the default CCP values. Note that Function 108, Get/Set 
Program Return Code, can be used to pass a two byte value to the chained program. 

Function 47 does not return any values to the calling program and any encoun- 
tered errors are handled by the CCP. 



3 BDOS Calls: Function 48 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 48: FLUSH BUFFERS 



Entry Parameters: 

Registers C: 30H 

E: Purge Flag 

Returned Value: 

Registers A: Error Flag 

H: Physical Error 



The Flush Buffers function forces the write of any write-pending records contained 
in internal blocking/deblocking buffers. If register E is set to OFFH, this funaion also 
purges all active data buffers. Programs that provide write with read verify support 
need to purge internal buffers to ensure that verifying reads actually access the disk 
instead of returning data that is resident in internal data buffers. The CP/M 3 PIP 
utility is an example of such a program. 

Upon return, register A is set to zero if the flush operation is successful. If a 
physical error is encountered, the Flush Buffers function performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is in 
the default mode, a message identifying the error is displayed at the console and the 
calhng program is terminated. Otherwise, the Flush Buffers funaion returns to the 
calling program with register A set to OFFH and register H set to the following 
physical error code: 

01 : Disk I/O error 

02 : Read/only disk 
04 : Invalid drive error 



RESEARCH™ 



CP/M 3 Prograr 



3 BDOS Calls: Function 49 



BDOS FUNCTION 49: 


GET / SET SYSTEM 
CONTROL BLOCK 


Entry Parameters; 

Registers C; 

DE: 

Returned Value; 
Registers A; 
HL; 


31H 

SCB PB Aiidress 

Returned Byte 
Returned Word 



Function 43 allows access to parameters located in the CP/M 3 System Control 
Block (SCB). The SCB is a 100-byte data structure residing within the BDOS that 
contains flags and data used by the BDOS, CCP and other system components. Note 
that Function 49 is a CP/M 3 specific function. Programs intended for both MP/M U 
and CP/M 3 should either avoid the use of this function or isolate calls to this 
funaion in CP/M 3 version-dependent sections. 

To use Function 49, the calling program passes the address of a data structure 
called the SCB parameter block in register pair DE. This data structure identifies the 
byte or word of the SCB to be updated or returned. The SCB parameter block is 
defined as: 



5CBPB: 



DB OFFSET 

DB SET 



DM VALUE 



; Offset within SCB 

i OFFH if ffttin* a bvte 

• OFEH if settind a uo rd 

i OOIH - OFDH are reserued 

; OOOH if a aet operation 

I Byte or word ualue to be set 



The OFFSET parameter identifies the offset of the field within the SCB to be updated 
or accessed. The SET parameter determines whether Function 49 is to set a byte or 
word value in the SCB or if it is to return a byte from the SCB. The VALUE 
parameter is used only in set calls. In addition, only the first byte of VALUE is 
referenced in set byte calls. 



B DIGITAL RESEARCH" 



3 BDOS Calls; Function 49 



CP/M 3 Programmer's Guide 



Use caution when you set SCB fields. Some of these parameters reflea the current 
state of the operating system. If they are set to invalid values, software errors can 
resuh. In general, do not use Function 49 to set a system parameter if another BDOS 
function can achieve the same result. For example. Function 49 can be called to 
update the Current DMA Address field within the SCB. This is not equivalent to 
making a Function 26, Set DMA Address call, and updating the SCB Current DMA 
field in this way would result in system errors. However, you can use Function 49 to 
return the Current DMA address. The System Control Block is summarized in the 
following table. Each of these fields is documented in detail in Appendix A. 



Table 3-4. System Control Block 



Offia 


Description 


00 — 


04 


Reserved For System Use 


OS 




BDOS version number 


06 — 


09 


User Flags 


OA — 


OF 


Reserved For System Use 


10 — 


11 


Program Error return code 


12- 


19 


Reserved For System Use 


lA 




Console Width (columns) 


IB 




Console Column Position 


IC 




Console Page Length 


ID- 


21 


Reserved For System Use 


22- 


23 


CONIN Redirection flag 


24- 


25 


CONOUT Redirection flag 


26- 


27 


AUXIN Redirection flag 


28 - 


29 


AUXOUT Redirection flag 


2A- 


2B 


LSTOUT Redirection flag 


2C 




Page Mode 


2D 




Reserved For System Use 


2E 




CTRL-H Active 


2F 




Rubout Active 


30- 


32 


Reserved For System Use 


33- 


34 


Console Mode 


35 - 


36 


Reserved For System Use 


37 




Output Delimiter 


38 




List Output Flag 


39- 


3B 


Reserved For System Use 



n 

n 

1 

n 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 49 



Table 3-4. (continued) 



Offset 


Descriptioft 


3C — 3D 


Current DMA Address 


3E 


Current Disk 


3F-43 


Reserved For System Use 


44 


Current User Number 


45 — 49 


Reserved For System Use 


4A 


BDOS Multi-Sector Count 


4B 


BDOS Error Mode 


4C— 4F 


Drive Search Chain (DISKS A:,E:,F;) 


50 


Temporary File Drive 


51 


Error Disk 


52 — 56 


Reserved For System Use 


57 


BDOS (lags 


58 — 5C 


Date Stamp 


5D-5E 


Common Memory Base Address 


5F — 63 


Reserved For System Use 



If Function 49 is called with the OFFSET parameter of the SCB parameter block 
greater than 63H, the funaion performs no action but returns with registers A and 
HL set to zero. 



I1D1GITAL RESEARCH™ - 



3 BDOS Calls: 



CP/M 3 Programmer's Guide — • 



BDOS FUNCTION 50: DIRECT BIOS CALLS 



Entry Parameters: 

Registers C: 32H 

DE: BIOS PB Address 

Returned Value: BIOS RETURN 



Funaion 50 provides a direct BIOS call through the BDOS to the BIOS. The 
calhng program passes the address of a data structure called the BIOS Parameter 
Block (BIOSPB) in register pair DE. The BIOSPB contains the BIOS function number 
and register contents as shown below: 



BIOSPB: 


db FUNC 




db AREG 




dw BCREG 




dw DEREG 




du HLREG 



BIOS f unct i on no . 
A register contents 
BC register contents 
DE register contents 
HL reSister contents 



System Reset (Function 0) is equivalent to Function 50 with a BIOS function 

lumber of 1. 



Note that the register pair BIOSPB fields (BCREG, DEREG, HLREG) arc defined 
in low byte, high byte order. For example, in the BCREG field, the first byte contains 

the C register value, the second byte contains the B register value. 

Under CP/M 3, direct BIOS calls via the BIOS jump vector are only supported for 
the BIOS Console I/O and List funaions, You must use Function 50 to call any other 
BIOS functions. In addition, Function 50 intercepts BIOS Function 27 (Select Mem- 
ory) calls and returns with register A set to zero. Refer to the CP/M Plus (CP/M 
Version 3) Operating System System Guide for the definition of the BIOS funaions 
and their register passing and return conventions. 



m DIGITAL RESEARCH'" 



-■ CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 59 



BDOS FUNCTION 59: LOAD OVERLAY 



Entry Parameters: 

Registers C: 3BH 

DE: FCB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



n Only transient programs with an RSX header can use the Load Overlay function 

' because BDOS Function 59 is supponed by the LOADER module. The calling pro- 

gram must have a header to force the LOADER to remain resident after the program 
^, is loaded (see Section 1.3). 

Function 59 loads either an absolute or relocatable module. Relocatable modules 
.m, are identified by a filetype of PRL. Funaion 59 docs not call the loaded module. 

I| 

The referenced FCB must be successfully opened before Function 59 is called. The 
load address is specified in the first two random record bytes of the FCB, rO and rl. 

nThe LOADER returns an error if the load address is less than lOOH, or if performing 
the requested load operation would overlay the LOADER, or any other Resident 
System Extensions that have been previously loaded. 

I i When loading relocatable files, the LOADER requires enough room at the load ad- 

dress for the complete PRL file including the header and bit map (see Appendix B}. 
^^ Otherwise an error is returned. Function 59 also returns an error on PRL file load 
: requests if the specified load address is not on a page boundary. 

Upon return, Function 59 sets register A to zero if the load operation is successful. 

Pi If the LOADER RSX is not resident in memory because the calling program did not 

1 have a RSX header, the BDOS returns with register A set to OFFH and register H set 

to zero. If the LOADER detects an invalid load address, or if insufficient memory is 

_ available to load the overlay. Function 59 returns with register A set to OFEH. All 

I other error returns are consistent with the error codes returned by BDOS Function 

20, Read Sequential. 



PDIGITAL RESEARCH'" 



3 BDOS Calk: Function 60 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 60: CALL RESIDENT SYSTEM 
EXTENSION 



Entry Parameters: 

Registers C: 3CH 

DE: RSX PB Address 

Returned Value: 

Registers A: Error Code 

H: Physical Error 



Function 60 is a special BDOS function that you use when you call Resident 
System Extensions. The RSX subfunction is specified in a structure called the RSX 
Parameter Block, defined as follows: 



db FUNC 

db NUMPARMS 

du PflRMETERl 

dw PARMETER2 



RSX Funct ion m, 
Number of word 
Pa ramete r 1 
Pa ramele r 2 



mber 
paraMe te rs 



dw PARMETERn ? Parameter n 

RSX modules filter all BDOS calls and capture RSX funaion calls that they can 
handle. If there is no RSX module present in memory that can handle a specific RSX 
funaion call, the call is not trapped, and the BDOS returns OFFH in registers A and 
L. RSX function numbers from to 127 are available for CP/M 3 compatible soft- 
ware use. RSX function numbers 128 to 255 are reserved for system use. 



- id DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 98 



BDOS FUNCTION 98: FREE BLOCKS 



Entry Parameters: 

Register C: 62H 

Returned Value: 

Registers A; Error Flag 

H: Physical Error 



The Free Blocks function scans all the currently logged-in drives, and for each 
drive returns to free space all temporarily- allocated data blocks. A temporarily-allo- 
cated data block is a block that has been allocated to a file by a BDOS write 
operation but has not been permanently recorded in the directory by a BDOS close 
operation. The CCP calls Function 98 when it receives control following a system 
warm start. Be sure to close your file, particularly any file you have written to, prior 
to calling Function 98. 

In the nonbanked version of CP/M 3, Function 98 frees only temporarily allocated 
blocks for systems that request double allocation vectors in GENCPM. 

Upon return, register A is set to zero if Function 98 is successful. If a physical 
error is encountered, the Free Blocks function performs different actions depending 
on the BDOS error mode (see Function 45). If the BDOS error mode is in the default 
mode, a message identifying the error is displayed at the console and the calling 
program is terminated. Otherwise, the Free Blocks function returns to the calling 
program with register A set to OFFH and register H set to the following physical 
error code: 



04 : Invalid drive error 



eorCITAl. RESEARCH"* - 



3 BDOS Calls: 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 99: TRUNCATE FILE 



Entry Parameters: 

Registers C: 63H 

DE: FCB Address 

Returned Value: 

Registers A: Directory Code 

H: Extended or Physical Error 



The Truncate File funaion sets the last record of a file to the random record 
number contained in the referenced FCB. The caUing program passes the address of 
the FCB in register pair DE, with byte of the FCB specifying the drive, bytes 1 
through 11 specifying the filename and filetype, and bytes 33 through 35, rO, rl, and 
r2, specifying the last record number of the file. The last record number is a 24 bit 
value, stored with the least significant byte first, rO, the middle byte next, rl, and the 
high byte last, r2. This value can range from to 262,143, which corresponds to a 
maximum value of 3 in byte r2. 

If the file specified by the referenced FCB is password protected, the correct pass- 
word must be placed in the first eight bytes of the current DMA buffer, or have been 
previously established as the default password (see Function 106). 

Function 99 requires that the file specified by the FCB not be open, particularly if 
the file has been written to. In addition, any activated FCBs naming the file are not 
valid after Function 99 is called. Close your file before calling Function 99, and then 
reopen it after the call to continue processing on the file. 



- m DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 99 

Function 99 also requires that the random record number field of the referenced 
FCB specify a value less than the current file size. In addition, if the file is sparse, the 
random record field must specify a record in a region of the file where data exists. 

Upon return, the Truncate function returns a Directory Code in register A with the 
value if the Truncate function is successful, or OFFH, 255 decimal, if the file is not 
found or the record number is invalid. Register H is set to zero in both of these 
cases. If a physical or extended error is encountered, the Truncate function performs 
different aaions depending on the BDOS error mode (see Function 45). If the BDOS 
error mode is in the default mode, a message identifying the error is displayed at the 
console and the program is terminated. Otherwise, the Truncate function returns to 
the calling program with register A set to OFFH and register H set to one of the 
following physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 

03 : Read-Only file 

04 : Invalid drive error 
07 : File password error 

09 : ? in filename or filetype field 



El DIGITAL RESEARCH™ 



3 BDOS Calls: Function 100 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 100: SET DIRECTORY LABEL 



Entry Parameters: 

Registers C: 64H 

DE: FCB Address 



Returned Value; 

Registers A: 

H: 



Directory Code 

Physical or Extended Error 



The Set Directory Label function creates a directory label, or updates the existing 
directory label for the specified drive. The calling program passes in register pair DE 
the address of an FCB containing the name, type, and extent fields to be assigned to 
the directory label. The name and type fields of the referenced FCB are not used to 
locate the directory label in the directory; they are simply copied into the updated or 
created directory label. The extent field of the FCB, byte 12, contains the user's 
specification of the directory label data byte. The definition of the directory label 
data byte is: 

bit 7 - Require passwords for password- protected files 
(Not supported in nonbanked CP/M 3 systems) 
6 - Perform access date and time stamping 
5 - Perform update date and time stamping 
4 - Perform create date and time stamping 
- Assign a new password to the directory label 

If the current directory label is password protected, the correct password must be 
placed in the first eight bytes of the current DMA, or have been previously estab- 
lished as the default password (see Function 106), If bit 0, the low-order bit, of byte 
12 of the FCB is set to 1, it indicates that a new password for the directory label has 
been placed in the second eight bytes of the current DMA. 

Note that Function 100 is implemented as an RSX, DIRLBL.RSX, in nonbanked 
CP/M 3 systems. If Function 100 is called in nonbanked systems when the DIRLBL.RSX 
is not resident, an error code of OFFH is returned. 



- H DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 3 BDOS Calls; Function 100 

Function 100 also requires that the referenced directory contain SFCBs to activate 
date and time stamping on the drive. If an attempt is made to activate date and time 
stamping when no SFCBs exist. Function 100 returns an error code of OFFH in 
register A and performs no aaion. The CP/M 3 INITDIR utility initializes a directory 
for date and time stamping by placing an SFCB record in every fourth entry of the 
directory. 

Function 100 returns a Directory Code in register A with the value if the direc- 
tory label create or update is successful, or OFFH, 255 decimal, if no space exists in 
the referenced direaory to create a directory label, or if date and time stamping was 
requested and the referenced directory did not contain SFCBs. Register H is set to 
zero in both of these cases. If a physical error or extended error is encountered, 
Function 100 performs different actions depending on the BDOS error mode (see 
Function 45). If the BDOS error mode is the default mode, a message identifying the 
error is displayed at the console and the calling program is terminated. Otherwise, 
Function 100 returns to the calling program with register A set to OFFH and register 
H set to one of the following physical or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 

04 : Invalid drive error 
07 : File password error 



a DIGITAL RESEARCH™ - 



3 BDOS Calls;. Function 101 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 101; RETURN DIRECTORY 
LABEL DATA 


Entry Parameters; 

Registers C; 

E; 


65H 
Drive 


Returned Value; 
Registers A; 

H; 


Directory Label 
Data Byte 
Physical Error 



The Return Directory Label Data function returns the data byte of the directory 
label for the specified drive. The calling program passes the drive number in register 
E with for drive A, 1 for drive B, and so on through 15 for drive P in a full sixteen 
drive system. The format of the directory label dat3 byte is shown below; 

bit 7 - Require passwords for password protected files 
6 - Perform access date and time stamping 
5 - Perform update date and time stamping 
4 - Perform create date and time stamping 
- Directory label exists on drive 

Funaion 101 returns the directory label data byte to the calling program in register 
A. Register A equal to zero indicates that no direaory label exists on the specified 
drive. If a physical error is encountered by Function 101 when the BDOS Error mode 
is in one of the return modes (see Function 45), this function returns with register A 
set to OFFH, 255 decimal, and register H set to one of the following: 

01 : Disk I/O error 
04 : Invalid drive error 



- H DIGITAL RESEARCH™ 



CP/M 3 ProB rammer's Guide 



3 BDOS Calls: Function 102 



BDOS FUNCTION 102; 



READ FILE DATE STAMPS 
AND PASSWORD MODE 



Entry Parameters: 

Registers C: 66H 

DE: FCB Address 



Returned Value: 

Registers A: 

H: 



Directory Code 
Physical Error 



Function 102 returns the date and time stamp information and password mode for 
the specified file in byte 12 and bytes 24 through 32 of the specified FCB. The calling 
program passes in register pair DE, the address of an FCB in which the drive, file- 
name, and filetype fields have been defined. 

If Function 102 is successful, it sets the following fields in the referenced FCB; 

byte 12 : Password mode field 
bit 7 - Read mode 
bit 6 - Write mode 
bit 4 - Delete mode 



; been assigned a password. In non- 



Byte 12 equal to zero indicates the file has m 
banked systems, byte 12 is always set to zero. 

byte 24 - 27 : Create or Access time stamp field 
byte 28 - 31 ; Update time stamp field 

The date stamp fields are set to binary zeros if a stamp has not been made. The 
format of the time stamp fields is the same as the format of the date and time 
structure described in Function 104. 



IB DIGITAL RESEARCH'" 



CP/M 3 Program 



Upon return. Function 102 returns a Directory Code in register A with the value 
zero if the function is successful, or OFFH, 255 decimal, if the specified file is not 
found. Register H is set to zero in both of these cases. If a physical or extended error 
is encountered. Function 102 performs different actions depending on the BDOS 
error mode (see Function 45). If the BDOS error mode is in the default mode, a 
message identifying the errot is displayed at the console and the calling program is 
terminated. Otherwise, Function 102 returns to the calling program with register A 
set to OFFH and register H set to one of the following physical or extended error 
codes; 



01 : Disk lyO error 

04 : Invalid drive error 

09 ; ? in filename or filetype field 



- IS DIGITAL RESEARCH ' 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Funttion 103 



BDOS FUNCTION 103: WRITE FILE XFCB 



Entry Parameters: 

Registers C; 67H 

DE: FCB Address 



Returned Value: 

Registers A: 

H: 



Directory Code 
Physical Error 



The Write File XFCB function creates a new XFCB or updates the existing XFCB 
for the specified file. The calling program passes in register pair DE the address of an 
FCB in which the drive, name, type, and extent fields have been defined. The extent 
field specifies the password mode and whether a new password is to be assigned to 
the file. The format of the extent byte is shown below; 

FCB byte 12 (ex) ; XFCB password mode 
bit 7 - Read mode 
bit 6 - Write mode 
bit 5 - Delete mode 

bit - Assign new password to the file 

If the specified file is currently password protected, the correct password must reside 
in the first eight bytes of the current DMA, or have been previously established as 
the default password (see Function 106). If bit is set to 1, the new password must 
reside in the second eight bytes of the current DMA. 



i DIGITAL RESEARCH"' 



3 BDOS Calls: Function 103 CP/M 3 Programmer's Guide 

Upon return. Function 103 returns a Directory Code in register A with the vaiue 
zero if the XFCB create or update is successful, or OFFH, 255 decimal, if no directory 
label exists on the specified drive, or the file named in the FCB is not found, or no 
space exists in the directory to create an XFCB. Function 103 also returns with OFFH 
in register A if passwords are not enabled by the referenced direaory's label. On 
nonbanked systems, this function always returns with register A = OFFH because 
passwords are not supported. Register H is set to zero in all of these cases. If a 
physical or extended error is encountered, Function 103 performs different actions 
depending on the BDOS error mode (see Function 45). If the BDOS error mode is 
the default mode, a message identifying the error is displayed at the console and the 
calling program is terminated. Otherwise, Function 103 returns to the calling pro- 
gram with register A set to OFFH and register H set to one of the following physical 
or extended error codes: 

01 : Disk I/O error 

02 : Read-Only disk 
04 : Invalid drive error 
07 : File password error 

09 : ? in filename or filetype field 



ia DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 104 



BDOS FUNCTION 104: SET DATE AND TIME 



Entry Parameters: 

Registers C: 68H 

DE: DAT Address 

Returned Value; none 



The Set Date and Time function sets the system internal date and time. The calling 
program passes the address of a 4-byte structure containing the date and time speci- 
fication in the register pair DE. The format of the date and time (DAT) data structure 



byte - 1 : Date field 
byte 2 : Hour field 
byte 3 : Minute field 

The date is represented as a 16-bit integer with day 1 corresponding to January 1, 
1978. The time is represented as two bytes: hours and minutes are stored as two 
BCD digits. 

This function also sets the seconds field of the system date and time to zero. 



a DIGITAL RESEARCH" 



3 BDOS Calls; Fun. 



CP/M 3 Programm 



BDOS FUNCTION lOJ. GET DATE AND TIME 


Entry Parameters; 

Registers C, 

DE: 

Returned Value: 
Register A; 
DAT set 


69H 

DAT Address 

seconds 



The Get Date and Time function obtains the system internal date and time. The 
calling program passes in register pair DE, the address of a 4-byte data structure 
which receives the date and time values. The format of the date and time, DAT, data 
structure is the same as the format described in Function 104. Funaion 105 also 
returns the seconds field of the system date and time in register A as a two digit BCD 
value. 



m DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 106 



BDOS FUNCTION 106: SET DEFAULT PASSWORD 



Entry Parameters: 

Registers C: 6AH 

DE: Password Address 

Returned Value: none 



The Set Default Password function allows a program to specify a password value 
before a file protected by the password is accessed. When the file system accesses a 
pas sword -protected file, it checks the current DMA, and the default password for the 
correct value. If either value matches the file's password, full access to the file is 
allowed. Note that this funaion performs no action in nonbanked CP/M 3 systems 
because file passwords are not supported. 

To make a Function 106 call, the calling program sets register pair DE to the 
address of an 8-byte field containing the password. 



DIGITAL RESEARCH" 



3 BDOS Calls: Function 107 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 107: RETURN SERIAL NUMBER 



Entry Parameters: 

Registers C: 6BH 

DE: Serial Number Field 

Returned Value: Serial number field set 



Funaion 107 returns the CP/M 3 serial number to the 6-byte field addressed by 
register pair DE. 



19 DIGITAL RESEARCH™ 



CP/M 3 Programm 



3 BDOS Calls: Function 10 



BDOS FUNCTION 108: GET/SET PROGRAM RETURN 




CODE 


Entry Parameters; 




Registers C; 


6CH 


DEi 


OFFFFH (Get) or 




Program Return Code (Set) 


Returned Value; 




Register HL; 


Program Return Code or (no value) 



CP/M 3 allows programs to set a return code before terminating. This provides a 

mechanism for programs to pass an error code or value to a following job step in 

ij batch environments. For example, Program Return Codes are used by the CCP in 

' ' CP/M 3's conditional command hne batch facility. Conditional command lines are 

command lines that begin with a colon, :. The execution of a conditional command 

7^ depends on the successful execution of the preceding command, The CCP tests the 

' I return code of a terminating program to determine whether it successfully completed 

or terminated in error. Program return codes can also be used by programs to pass 

■^ an error code or value to a chained program (see Function 47, Chain To Program). 

A program can set or interrogate the Program Return Code by calling Function 

108. If register pair DE = OFFFFH, then the current Program Return Code is returned 

Ij in register pair HL. Otherwise, Funaion 108 sets the Program Return Code to the 

' ' value contained in register pair DE. Program Return Codes are defined in Table 3-5. 



B DIGITAL RESEARCH'" 



3 BDOS Calls: Function 108 CP/M 3 Programmer's Guide 

Table 3-5. Program Return Codes 



Code 


Meaning 


0000 — FEFF 


Successful return 


FFOO — FFFE 


Unsuccessful return 


0000 


The CCP initializes the Program Return Code to zero unless 
the program is loaded as the result of program chain. 


FF80 — FFFC 


Reserved 


FFFD 


The program is terminated because of a fatal BDOS error. 


FFFE 


The program is terminated by the BDOS because the user 
typed a CTRL-C. 



a DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 



3 BDOS Calls; Function 109 



BDOS FUNCTION 109: GET/SET CONSOLE MODE 



Entry Parameters: 

Registers C: 6DH 

DE: OFFFFH (Get) or Console Mode (Set) 

Returned Value: 
Register HL: Console Mode or [no value) 



A program can set or interrogate the Console Mode by calling Function 109. If 
register pair DE = OFFFFH, then the current Console Mode is returned in register 
HL. Otherwise, Function 109 sets the Console Mode to the value contained in regis- 
ter pair DE. 

The Console Mode is a 16-bit system parameter that determines the action of 
certain BDOS Console I/O functions. The definition of the Console Mode is; 

bit = 1 - CTRL-C only status for Funaion 11. 
= - Normal status for Function 11. 



bit 1 



^ 1 - Disable stop scroll, CTRL-S, start scroll, CTRL-Q, support. 
- - Enable stop scroll, start scroll support. 



bit 2 = 1 - Raw console output mode. Disables tab expansion for Functions 2, 
9 and 111. Also disables printer echo, CTBL-P, support. 
= - Normal console output mode. 

bit 3 = 1 - Disable CTRL-C program termination 
= - Enable CTRL-C program termination 



M DIGITAL RESEARCH'" 



3 BDOS Calls; Function 109 CP/M 3 Programmer's Guide 

bits 8,9 - Console status mode for RSXs that perform console input redirec- 
tion from a file. These bits determine how the RSX responds to 
console status requests. 

bit 8 = 0, bit 9 = - conditional status 

bit 8 = 0, bit 9 = 1 - false status 

bit 8 = 1, bit 9 = - true status 

bit 8 = 1, bit 9 = 1 - bypass redirection 



Note that the Console Mode bits are numbered from right to left. 

The CCP initiahzes the Console Mode to zero when it loads a program unless the 
program has an RSX that overrides the default value. Refer to SeCTion 2,2.1 for 
detailed information on Console Mode. 



m DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 110 



BDOS FUNCTION 110: GET/SET OUTPUT DELIMITER 



Entry Parameters: 

Registers C: 6EH 
DE: 
E: 



OFFFFH (Get) or 
Output Delimiter (Set) 



Returned Value: 

Register A: Output Delimiter or (no value) 



A program can set or interrogate the current Output Delimiter by calling Function 
110, If register pair DE = OFFFFH, then the current Output Delimiter is returned in 
register A. Otherwise, Function 110 sets the Output Delimiter to the value contained 
in register £. 

Function 110 sets the string delimiter for Function 9, Print String. The default 
delimiter value is a dollar sign, $. The CCP restores the Output Delimiter to the 
default value when a transient program is loaded. 



B DIGITAL REStARCH- 



3 BDOS Calls: Function 111 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 111: PRINT BLOCK 



Entry Parameters: 

Registers C: 6FH 

DE: CCB Address 

Returned Value: none 



The Print Block function sends the character string located by the Charaaer Con- 
trol Block, CCB, addressed in register pair DE, to the logical console, CONOUT:. If 
the Console Mode is in the default state (see Section 2.2.1), Function 111 expands 
tab characters, CTRL-1, in columns of eight characters. It also checks for stop scroll, 
CTRL-S, start scroll, CTRL-Q, and echoes to the logical list device, LST:, if printer 
echo, CTRL-P, has been invoked. 

The CCB format is: 



byteO 
byte 2 



1 : Address of charaaer string (word value) 
3 : Length of character string (word value) 



- iSDIGlTAL RESEARCH™ 



CP/M 3 Programmer's Guide 



3 BDOS Calls: Function 112 



BDOS FUNCTION 1 12: LIST BLOCK 



Entry Parameters: 

Registers C: 70H 

DE: CCB Address 

Returned Value: none 



The List Block function sends the character string located by the Character Control 
Block, CCB, addressed in register pair DE, to the logical list device, LST:. 

The CCB format is; ■• 

byte - 1 : Address of character string (word value) 
byte 2 - 3 : Length of character string (word value) 



Bl DIGITAL RESEARCH™ - 



3 BDOS Calls: Function 152 



CP/M 3 Programmer's Guide 



BDOS FUNCTION 152: PARSE FILENAME 



Entry Parameters: 

Registers C: 98H 

DE: PFCB Address 

Returned Value: 
Register HL: Return cckIc 
Parsed file control block 



The Parse Filename function parses an ASCII file specification and prepares a File 
Control Block, FCB. The catling program passes the address of a data structure called 
the Parse Filename Control Block, PFCB, in register pair DE. The PFCB contains the 
address of the input ASCII filename string followed by the address of the target FCB 
as shown below: 



PFCB: DW INPUT 
DW FCB 



Address of input ASCII string 
Address of target FCB 



The maximum length of the input ASCII string to be parsed is 128 bytes. The target 
FCB must be 36 bytes in length. 



Funaion 152 assumes the input string 



file specifications in the following 



{d:}fiIename{,typ}{;password} 

where items enclosed in curly brackets are optional. Function 152 also accepts iso- 
lated drive specifications d: in the input string. When it encounters one, it sets the 
filename, filetype, and password fields in the FCB to blank. 



- m DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 152 

The Parse Filename function parses the first file specification it finds in the input 
string. The function first eliminates leading blanks and tabs. The function then assumes 
that the file specification ends on the first delimiter it encounters that is out of 
context with the specific field it is parsing. For instance, if it finds a colon, and it is 
not the second charaaer of the file specification, the colon delimits the entire file 
specification. 

Function 152 recognizes the following charaaers as delimiters: 

space 

tab 

return 

null 

; (semicolon) - except before password field 

- (equal) 

< (less than) 

> (greater than) 

. (period) - except after filename and before filetype 

: (colon) - except before filename and after drive 

, (comma) 

I (vertical bar) 

[ (left square bracket) 

] (right square bracket) 

If Function 152 encounters a non-graphic character in the range 1 through 31 not 
listed above, it treats the character as an error. The Parse Filename function initializes 
the specified FCB shown in Table 3-6. 



m DIGITAL RESEARCH™ 



3 BDOS Calls: Function 152 



CP/M 3 Programmer's Guide 



Tabic 3-6. FCB Fonnat 



byte The drive field is set to the specified drive. If the drive is not 

specified, the default drive code is used. = default, 1 = A, 



byte 1-8 The name is set to the specified filename. All letters are con- 

verted to upper-case. If the name is not eight characters long, 
the remaining bytes in the filename field are padded with blanks. 
If the filename has an asterisk, *, all remaining bytes in the 
filename field are filled in with question marks, ?. An error 
occurs if the filename is more than eight bytes long. 

byte 9-11 The type is set to the specified filetype. U no filetype is speci- 

fied, the type field is initialized to blanks. All letters are con- 
verted to upper-case. If the type is not three characters long, 
the remaining bytes in the filetype field are padded with blanks. 
If an asterisk, *, occurs, all remaining bytes are filled in with 
question marks, ?. An error occurs if the type field is more 
than three bytes long. 

byte 12-15 Filled in with zeros. 

byte 16-23 Tlie password field is set to the specified password. If no pass- 

word is specified, it is initialized to blanks. If the password is 
less than eight characters long, remaining bytes are padded 
with blanks. All letters are converted to upper-case. If the pass- 
word field is more than eight bytes long, an error occurs. Note 
that a blank in the first position of the password field implies 
no password was specified. 

byte 24-31 Reserved for system use. 



i DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 3 BDOS Calls: Function 152 

If an error occurs, Function 152 returns an OFFFFH in register pair HL. 

On a successful parse, the Parse Filename function checks the next item in the 
input string. It skips over trailing blanks and tabs and looks at the next character. If 
the character is a null or carriage return, it returns a indicating the end of the input 
string. If the character is a delimiter, it returns the address of the delimiter. If the 
character is not a delimiter, it returns the address of the first trailing blank or tab. 



If the first non-blank or non-tab character in the input string is a null, 0, or 
carriage return, the Parse Filename function returns a zero indicating the end of 
string. 

If the Parse Filename function is to be used to parse a subsequent file specification 
in the input string, the returned address must be advanced over the delimiter before 
placing it in the PFCB. 



End of Section 3 



a DIGITAL RESEARCH'" 



n 
n 
n 
n 

n 
P 

n 
n 

n 



n 
n 
n 
n 
n 



Section 4 
Programming Examples 



The programs presented in this section illustrate how to use the BDOS functions 
described in the previous section. The examples show how to copy a file, how to 
dump a file, how to create or access a random access file, and how to write an RSX 



4.1 A Sample File-To-File Copy Program 

The following program illustrates simple file operations. You can create the pro- 
gram source file, COPY.ASM, using ED or another editor, and then assemble 
COPY.ASM using MAC™. MAC produces the file COPY.HEX. Use the utility 
HEXCOM to produce a C0PY.COM file that can execute under CP/M 3. 



The COPY program first sets the stack pointer to a local area, then moves the 
second name from the default area at 006CH to a 33-byte file control block named 
DFCB. The DFCB is then prepared for file operations by clearing the current record 
field. Because the CCP sets up the source FCB at 005CH upon entry to the COPY 
program, the source and destination FCBs are now ready for processing. To prepare 
the source FCB, the CCP places the first name into the default FCB, with the proper 
fields zeroed, including the current record field at 007CH. 

COPY continues by opening the source file, deleting any existing destination file, 
and then creating the destination file. If each of these operations is successful, the 
COPY program loops at the label COPY until each record is read from the source 
file and placed into the destination file. Upon completion of the data transfer, the 
destination file is closed, and the program returns to the CCP command level by 
jumping to BOOT. 



HI DIGITAL RESEARCH" 



4,1 A Sample Copy Program 



CP/M 3 Programmer's Guide 



0003 


prin 


OOOf 


> orcn 


0010 


ClDS 


0013 


> dele 


OOld 


reid 


0015 


gtil 


OOIE 


mki 


0100 




0100 


311b02 

1 


0103 


OelO 


OlOS 


llEcOO 


OlOS 


ZldiOt 


010b 


U Mfcb 


010c 


13 


OlOd 


77 


OlOt 


23 


OlOf 


Od 


Olio 


cZObOl 

1 


0113 


af 


Olid 


3Zfa01 



I hiir in fcb 



- m DIGITAL RESEARCH'" 



p CP/M 3 Program 



4.1 A Sample Copy Program 



0117 UScOO 

Olla cdGdOl 

Olid 11B701 

Oieo 3c 

0121 ccSlOl 



012a UdaOl 

OlZd cdezoi 

0130 119E01 

0133 3o 

0130 ccetOl 



0137 llScOO c 
013a caiBQl 
013d 67 
013e DZ5101 



OMl lldaOl 
0111 i:d7ii01 
Old? Ila901 
014a b7 
Oldb clElOl 
Olde C33701 



> 0151 lldaOl 
OI5d cdG«01 

^ 0157 ZltjbOl 

I I 015a 3c 

> 015b ccGlOl 



) dtiiii 
1 255 if t 



015« llccOl 



"1 01G3 

I 01G6 



oiei ot09 

I050C 
01G6 C30000 



11 DIGITAL RESEARCH'" 



4.1 A Sample Copy Program CP/M 3 Programmer's Guide 



017a 030500 



0187 GeSriOfnafili: i 
0196 GeGfZOSnDdir: i 
0U9 Sf757BfspacBi i 
Olbb 777Z695urprot: i 
Olec 63Gf700nDKiial! i 



Note that this program makes several simplifications and could be enhanced. First, 
it does not check for invalid filenames that could, for example, contain ambiguous 
references. This situation could be detected by scanning the 32-byte default area 
staning at location 005CH for ASCII question marks. To check that the filenames 
have, in fact, been included, COPY could check locations 005DH and 006DH for 
nonbtank ASCII characters. Finally, a check should be made to ensure that the source 
and destination filenames are different. Speed could be improved by buffering more 
data on each read operation. For example, you could determine the size of memory 
by fetching FBASE from location 0006H, and use the entire remaining portion of 
memory for a data buffer. You could also use CP/M 3's Multi-Sector I/O facility to 
read and write data in up to 16K units. 



CP/M 3 Programmer's Guide 



4.2 A Sample File Dump Utility 



4.2 A Sample File Dump Utility 

The following dump program reads an input file specified in the CCP command 
line, and then displays the content of each record in hexadecimal format at the 
console. 



0100 
0005 = 

0001 = 

0002 ■ 
0009 = 
000b ' 
OOOf = 



005c ■ 
OOSd ■■ 
0OB5 ■ 



fcbdn 
fcbfn 
fcbft 



tcb*3 Idi) 



OlOa ZZ1502 
0107 31570Z 



" OlOa 



OlOf oZlbOl 



a DIGITAL RESEARCH ' 



n 

4.2 A Sample File Dump Utility CP/M 3 Programmer's Guide ^ 



ouz 


llfSOl 


0115 


cd9c01 


0118 


035101 


011b 


3(S0 


Olid 


321302 


OIZO 


210000 


01Z3 


e! 


OlZfl 


cdaZOl 


01Z7 


■ 1 


0128 


di5101 


OlZb 


fl7 


OlZc 


7d 


OlZd 


eGOf 


012f 


ezaaoi 



0135 


cdSSOl 


013B 


Of 


0139 


ila5101 


i 0130 7c 


0I3d 


cdBfOl 


oiao 


7d 


Olfll 


□ dSfOl 


0141 


23 


0105 


3eZ0 


0147 


cd6501 


oiaa 


78 



Oiae C3Z301 



itt br fnb if end flit 



; for line fold 



@ DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 4.2 A Sample File Dump Utility 



i tnd at i 

0151 cd7Z01 call 

01S4 Zal502 Ihld 

0157 f9 iPhl 



01S9 tSdScS 
OlSc OcOb 
OlSe cdOSOO 
0161 cldltl 
0161 c9 



01Gb cdOSOO call bdoi 

OlBt cldltt far b'. far d! pd» hi rtitsrid 

0171 eg ret 



0172 3>0d 
017d cdESOl 
0177 3t0i 
0179 CdESOl 
017c c9 



017d 


eSOf 


017f 


ftOl 


OlSl 


dzesoi 


OlBfl 


0630 


01B6 


cSBbOl 


0IS9 


bS37 


018b 


cdBSOl 


018t 


c9 



m DIGITAL RESEARCH™ 



4.2 A Sample File Dump Utility 



CP/M 3 Programmer's Guide "^ 



oiaf f5 

0190 Ot 

0191 Of 

0192 Of 

0193 Of 
0191 Cd7d01 
0137 fl 
0199 cil7d01 
019b c9 



019c 0(09 
OlSe cdOSOO 
Olal c9 



;FrifH buffff fur 



OliZ 3al30Z 
OlaS fe90 
0U7 cZb301 



Olbe 7e 
Olbf b7 



iU byte Df buffo 



ii DIGITAL RESEARCH" 



F" CP/M 3 Programmer's Guide 



4,2 A Sample File Dump Utility 



—1 01c5 115c00 
' I 01c8 OeOf 

I-, Olcd c9 



Olce e5d5c5 

^ Oldl nscoo 

oida oeia 

OldG edO^OO 

01d9 cldlel 



I 32 liucl itii 



B DIGITAL RESEARCH™ - 



n 



4.3 A Sample Random Access Program CP/M 3 Programmer's Guide 

4.3 A Sample Random Access Program 

This example is an extensive but complete example of random access operation. 
The following program reads or writes random records upon command from the 
terminal. When the program has been created, assembled, and placed into a file ■-- 
labeled RANDOM.COM, the CCP level command ; 

(\>RANDOM X.DAT 

can start the test program. In this case, the RANDOM program looks for a file 
X.DAT and, if it finds it, prompts the console for input. If X.DAT is not found, 
RANDOM creates the file before displaying the prompt. Each prompt takes the "" 
form: ] 

next command? ^» 

and is followed by operator input, terminated by a carriage return. The input com- 
mands take the form: 

nW nR nF Q )_' 

where n is an integer value in the range to 262143, and W, R, F, and Q are simple -• 
command characters corresponding to random write, W, random read, R, random 
write with zero fill, F, and quit processing, Q, If you enter a W or F command, the 
RANDOM program issues the prompt: ^_ 

typedata: L 

You then respond by typing up to 127 characters, followed by a carriage return, ^ 
RANDOM then writes the character siring into the X.DAT file at record n. If you 
enter an F command, the RANDOM program fills previously unallocated data blocks 
with zeros before writing record n. If you enter the R command, RANDOM reads ^ 
record number n and displays the string value at the console. If you enter the Q ' 

command, the X.DAT file is closed, and the program returns to the console com- 
mand processor. In the interest of brevity, the only error message is: 



- m DIGITAL RESEARCH" \ 



CP/M 3 Programmer's Guide 



4.3 A Sample Random Access Program 



The program begins with an initialization section where the input file is opened or 
created, followed by a continuous loop at the label ready where the individual com- 
mands are interpreted. The program uses the default file control block at OOJCH and 
the default buffer at 0080H in all disk operations. The utility subroutines that follow 
contain the principal input line processor, called readc. This particular program shows 
the elements of random access processing and can be used as the basis for further 
program development. 





1 ♦•• 




0100 


" 


1 lOOh 


0000 ■ 


nbooi t 


u OOOOh 


ooos - 


bdos f 


u OOOSh 


0001 - 


coninp t 


u 1 


oooz - 


conaut 1 


u 2 


ooos ■ 


Pttrinl E 


u 3 


OOOA - 


rstrins e 


u 10 


oooc - 


utrsion t 


u 12 


OOOF - 


DPenf e 


u 15 


0010 - 


eloitr c 


u IG 


OOIB ■ 


MiKef e 


u 22 


0021 ■ 


rtidr c 


li 33 


0022 " 


writer e 


u 3a 


OOZB ■ 


urtrif t 


u CO 


OOSB > 


Ftrttf e 


u 152 


003C - 


rcb e 


u OOSch 


007D = 


ranrcD e 


u fcb*3 


007F - 


ranouf t 


u fob+3 


OOBO - 


buff e 


1 OOBOh 


OOOD - 


cr E 


u Odh 


OOOA - 


If t 


u Oah 



11 DIGITAL RESEARCH - 



4.5 A Sample Random Access Program 



CP/M 3 Programmer's Guide 



0103 OEOC 

0105 CDOSOO 

0108 FEZO 

OlOA OZiSOl 

OlOD 118102 

OHO CD310Z 

0113 C30000 



0116 


OEOF 


0118 


3A5DO0 


OllB 


FEZO 


OUD 


C2ZC01 


OIZO 


llEOOZ 


01Z3 


CD310Z 


OIZG 


CDZOOZ 


01Z9 


C31801 


OIZC 


115C00 


OIZF 


CDOSOO 


0132 


3C 


0133 


CZflBOl 


013B 


0E16 


0i3B 


IISCOO 


0I3D 


CDOSOO 


013E 


3C 


013F 


CZdDOl 


OldZ 


UAOOZ 


OldS 


CD310Z 


oias 


C30000 



i DIGITAL RESEARCH" 



CP/M 3 Programmer's Guide 



4.3 A Sample Random Access Program 



0MB C03C0Z 
OlflE ZJ7DO0 
0151 Z17FO0 
oisa 71 
0155 FE51 
0157 C2E901 



015A OEIO 
0I5C 115C0O 
015F CD0500 

otez 3C 

0tB3 CAFFOl 

otBB caoooo 



016E 11B302 
0171 CD310Z 
017a 0E7F 
0176 ZIBOOO 

0179 C5 
017fl E5 
017B CDOBOZ 
017E El 
017F CI 
01 BO FEOD 
OIBZ CABBOl 






> fill bufftr until i 






S DIGITAL RESEARCH'" 



4.3 A Sample Random Access Program 



CP/M 3 Programmer's Guide "^ 



01S5 77 
018G 23 

0187 OD 

0188 C27901 



inx h (next ta fill 

dcr c icountir foil doi. 

Jnz rloDF Ifni] of buffir? 

tnd of read Iddp. start 00 



OlBD OEZZ 

OlSF 115C00 

019Z C005D0 

0195 B7 

013G CZFFOl 

0199 C3dB01 



019C 


FEas 


019E 


CZCFOl 


OlAl 


11B30Z 


oifla 


C0310Z 


01fl7 


0E7F 


oins 


ZIBOOO 


OlflC 


CS 


OlflD 


E5 


OlftE 


CD080Z 


0161 


El 


OIBZ 


CI 


0103 


FEOD 


01B5 


CflBEOl 


OIBB 


77 


01B9 


23 


OlBfl 


OB 


OIBB 


CZACOl 



uritt the r< 
iKi d.f. 



ftor anath 



CBMianiii randi 



'il» i»ro fill? 



- IS DICrrAL RESEARCH'- 



CP/M 3 Programmer's Guide 



4.3 A Sample Random Access Program 



OICO OEZB 
01C2 115C0O 
01C5 CD0500 
01C8 B7 
01C9 C2FF01 

oicc c3aeoi 



ther rtcord 



I OlDd OEZl 
01D6 115C00 

n01D9 CDOSOO 
OlDC 67 
OlOD CZFFOl 



1h1 d.fcb 



OlEO CD1502 
01E3 OEBO 
01E5 ZIBOOO 

01E8 7E 
01E9 23 
OlEfl Ee7F 
OlEC CPIGOl 
0!EF C5 
OtFO E5 
OlFI FEZO 
01F3 DaOE02 
01F6 £1 
01F7 CI 
01F8 OD 
OIFg C2Ea01 
OlFC C3<]S01 



:aH crlf inew lint 

lul CflZB iMax 12B c 

HI h.buff Inent to ( 



i DIGITAL RESEARCH- 



n 

4.3 A Sample Random Access Program CP/M 3 Programmer's Guide "" 



I* utility subrautlnii foF eanioli l/i 



OlFF IIBFOZ 
0202 CD310Z 

0205 csaeoi 



0208 OEOl 
020fl CD0500 
OZOD C9 



020E 0E02 Hui e .Donout 

0210 5F MDU I >i (chine 

0211 CD0500 call bdos liind c 
021d C9 rit 



0215 3E0D 
0217 C00E02 
OZIA 3E0A 
02 IC CDOE02 
021F C9 



0220 11F102 
0223 OEOfl 
0225 CD0500 
OZZe 111303 
022B OESe 
022D CD0500 
0230 C3 



- IBDIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



4.3 A Sample Random Access Program 



023 1 DS 

0232 CDI502 

0235 Dl 

0236 0E09 
0238 CDOSOO 
023Q C9 






023C 


11D102 


Ixi 


d.rroMP 


t 




023F 


CD3102 


call 


print 




nd? 


02d2 


OEOA 


MUi 


c iritr 


ni 




aiaa 


IIFIOZ 


iHi 


a.CDnbti 


1 




oiai 


CD0500 


c!«.« 


bdDs 
d lint ii 


iriad 


coanind H 
t. lean it 


ozaa 


OEOO 


MVi 


c.O 


iitirt 


with 00 


ozac 


210000 


iKi 


h lO 


1 


0000 


02aF 


11F30Z 


Ixi 


d.canli 


niea»a 


nd lint 


0252 


lA re 


»4c: Idax 


d 


Inext 


canaand ch 


0293 


13 


inx 


d 


ito ne 


xt connand 


025a 


B7 


era 


a 


•canno 


t b* tni a 


0255 


CB 


fZ 








0Z56 


DE30 


III " 


ro.^nLi.er 


ic? 




025B 


FEOA 


cpi 


10 


icarrr 




0Z5fl 


D27302 


Jnc 


indrd 







S DIGITAL RESEARCH'" - 



4.3 A Sample Random Access Program 



CP/M 3 Programmer's Guide 



0Z5D 


F5 


0Z5E 


79 


025F 


23 


OZBO 


BF 


02G1 


F5 


02G2 


E5 


0ZG3 


29 


OZGa 


BF 


02G5 


Z9 


OZGG 


BF 


02G7 


CI 


02GS 


OS 


OZGg 


C! 


OZGfl 


SB 


OZSB 


CI 


OZGC 


OB 


OZBD 


OGOO 


OZGF 


OB 


0Z70 


CEOO 


0Z7Z 


4F 


0Z73 


DZ5Z0Z 


0Z7G 


C33C0Z 


0Z7a 


CG30 


0Z7B 


FEBl 


0Z7D 


oa 


0Z7E 


EG5F 


OZBO 


ca 



b i.2 * *B > *10 



02B1 73GF727279 

OZAO GEGFZOGdGS 

0ZB3 7a7B70BS20 

OZBF 65727ZBF72 

OZDl BE657a7aZ0 

02E0 G5GE7aG572 



inter f ilenane: 



-e DIGITAL RESEARCH" 



""J CP/M 3 Programmer's Guide 



4.3 A Sample Random Access Progra 





|«**«***<***«* 


■««■*«■<«**»••• 








;« fixid 


and u 


ariabl 


t d*ti ir 


. 


^ 


02F1 Zl 
02F2 
02F3 
0021 ' 


! 


b 


1 

32 
»-co 


;ien9 


h of 
tin* 

h 3Z 


onsol. buff«r 
Ue after read 
uffer 


0313 F30Z 
0315 5C0O 


pfncb: 




conl 
fo6 


,. 






0317 




s 


32 


il6 1 


«.! . 


icK 


0337 


ftacKi 













You could make the following major improvements to this program to enhance its 
operation. With some work, this program could evolve into a simple data base 
management system. You could, for example, assume a standard record size of 128 
bytes, consisting of arbitrary fields within the record. You could develop a program 
called GETKEY that first reads a sequential file and extraas a specific field defined 
by the operator. For example, the command 



GETKEY NAMES.DAT LASTNAME 10 20 



would cause GETKEY to read the data base file NAMES.DAT and extract the 
"LASTNAME" field from each record, starting at position 10 and ending at charac- 
ter 20. GETKEY builds a table in memory consisting of each particular LASTNAME 
field, along with its 16-bit record number location within the file. The GETKEY 
program then sorts this Hst and writes a new file, called LASTNAME.KEY. This list, 
sometimes called an inverted index, is an alphabetical list of LASTNAME fields with 
their corresponding record numbers. 

You could rename the program shown above to QUERY, and modify it so that it 
reads a sorted key file into memory. The command line might appear as 

QUERY NAMES.DAT LASTNAME.KEY 



i DIGITAL. RESEARCH" 



4.3 A Sample Random Access Program CP/M 3 Programmer's Guide 

Instead of reading a number, the QUERY program reads an alphanumeric string 
which is a particular key to find in the NAMES.DAT data base. Because the LAST- 
NAME.KEY list is sorted, you can find a particular entry quickly by performing a 
binary search, similar to looking up a name in the telephone directory. Start at both 
ends of the list and examine the entry halfway in between and, if not matched, split 
either the upper half or the lower half for the next search. You will quickly reach the 
item you are looking for, in log2(n) steps, where you will find the corresponding 
record number. Fetch and display this record at the console as the program illustrates. 

At this point, you are just getting started. With a little more work, you can allow 
a fixed grouping size, which differs from the 128-byte record shown above. You can 
accomplish this by keeping track of the record number as well as the byte offset 
within the record. Knowing the group size, you can randomly access the record 
containing the proper group, offset to the beginning of the group within the record, 
and read sequentially until the group size has been exhausted. 

Finally, you can improve QUERY considerably by allowing Boolean expressions 
that compute the set of records that satisfy several relationships, such as a LAST- 
NAME between HARDY and LAUREL and an AGE less than 45, Display all the 
records that fit this description. Finally, if your lists are getting too big to fit into 
memory, randomly access your key files from the disk as well. 



4.4 Construction of an RSX Program 

This section describes the standard prefix of a Resident System Extension (RSX) 
and illustrates the construaion of an RSX with an example. (See Section 1.6.4 for a 
discussion of how RSXs operate under CP/M 3.) RSX programs are usually written 
in assembler, but you can use other languages if the interface between the language 
and the calling conventions of the BDOS are set up properly. 



r: 



a DIGITAL REStAHCH" 



'- CP/M 3 Programmer's Guide 



4.4 Construction of an RSX Program 



4.4.1 The RSX Prefix 

The first 27 bytes of an RSX program contain a standard data structure called the 
R5X prefix. The RSX prefix has the following format: 



serial : 
start: 



remoue i 
nonbanK ; 



0»0 ,OtO,0 fO 
f test 
OcGh 



'123/15678' 



start of p rod ram 

JUMP instruction to 
neKt modul e in line 

p reui ous modul e 

remove f 1 a9 

nonbanK f 1 as 

any 8-character name 

loader flad 
rese rued area 



The only fields of the RSX prefix thai you n 
nonbank: flag, and the name: of the RSX. 



iaiize are the remove: flag, the 



For compatibility with previous releases of CP/M, the serial: field of the prefix is 
set to the serial number of the operating system by the LOADER module when the 
RSX is loaded into memory. Thus, the address in location 6 locates the byte follow- 
ing the serial number of the operating system with or without RSXs in memory. 

The start: field contains a jump instruaion to the beginning of the RSX code 
where the RSX tests to see if this BDOS function call is to be intercepted or passed 
on to the next module in line. 



The next: field contains a jump instruction to the next module in the chain or the 
LOADER module if the RSX is the oldest one in memory. The RSX program must 
make its own BDOS function calls by calling the next: entry point. 



El DIGITAL RESEARCH" 



4.4 Construction of an RSX Program CP/M 3 Programmer's Guide 

The prev: field contains the address of the preceding RSX in memory or location 5 
if the RSX is the first RSX in the chain. 

The remove: field controls whether the RSX is removed from memory by the next 
call to the LOADER module via BDOS function 59. If the remove: flag is OFFH, the 
LOADER removes the RSX from memory. Note that the CCP always calls the 
LOADER module during a warm start operation. An RSX that remains in memory 
past warm start because its remove: flag is zero, must set the flag at its termination 
to ensure its removal from memory at the following warm start. 

The nonbank: field controls when the RSX is loaded. If the field is OFFH, the 
LOADER only loads the module into memory on nonbanked CP/M 3 systems. 
Otherwise, the RSX is loaded into memory under both banked and nonbanked ver- 
sions of CP/M 3. 

The loader: flag identifies the LOADER RSX. When the LOADER module loads 
an RSX into memory, it sets this prefix flag of the loaded RSX to zero. However, the 
loader: flag in the LOADER'S prefix contains OFFH. Thus, this flag identifies the last 
RSX in the chain, which is always the LOADER. 

4.4.2 Example of RSX Use 

These two sample programs illustrate the use of an RSX program. The first 
program, CALLVERS, prints a message to the console and then makes a BDOS 
Function 12 call to obtain the CP/M 3 version number. CALLVERS repeats this 
sequence five times before terminating. The second program, ECHOVERS, is an RSX 
that intercepts the BDOS Function 12 call made by CALLVERS, prints a second 
message, and returns the version 0031H to CALLVERS. Although this example is 
simple, it illustrates BDOS function interception, stack swapping, and BDOS funaion 
calls within an RSX. 



CP/M 3 Programmer's Guide 



4.4 Construction of an RSX Program 





CflLLUERS 


OOOS = b 


OS e<* 


0009 = p 


tstr »i 


OOOC ' ^ 


rs e^ 


GOOD = c 




OOOfl = 1 





OIOZ 


D5 1 


sop: 


push 


0103 


0E09 




MUl 


0105 


lUEOl 




l>i 


0108 


CD0500 




call 


OlOB 


OEOC 




MUl 


OlOD 


CD0500 




call 


OHO 


7D 






0111 


323d01 




sta 


Olid 
0115 


Dl 
15 




POP 


0116 


C20Z01 




jnz 


0119 


OEOD 




nui 


OltB 


C30500 


all>« 


»! 


OllE 


ODOAZflZAZA 






013d 


00 c 


uruer 




0135 






end 






ECHOUERS RSX 


0009 




stfin 


eiu 


OOOD 






e«u 


OOOA 




f 


e^u 


0000 


0000000000 






0006 


C31BO0 




Jmp 


0009 


C3 n 






OOOA 


0000 






OOOC 


0000 P 


reu; 




OOOE 


FF r 


EUDU: 




OOOF 


00 n 


□ nbnk 




0010 


asflsaaaFSB 






OOiB 


000000 







RSX PREFIX STRUCTURE 
O.OiOtOfO.O i roDi 



E DIGITAL RESEARCH"' 



4.4 Construction of an RSX Program 



OOIC 


FEOC 


OOIE 


cflzaoo 


002 i 


C30S0O 


ooza 


ZIOOOO 


0027 


39 


00Z8 


zzsdoo 


OOZD 


317600 


OOZE 


0E09 


0030 


113EO0 


0033 


CDOSOO 


003G 


2ftsaoo 


0039 


F9 


003fl 


213100 


0030 


C9 


003E 


0DOA2A2A2A 


005(1 


0000 


0056 





Fttlltll 

I lOOSlh 



a DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 4,4 Construction of an RSX Program 

You can prepare the above programs for execution as follows: 

1. Assemble the CALLVERS program using MAC as follows: 
MAC CflLLyERS 

2. Generate a COM file for CALLVERS with HEXCOM: 
HEXCDM CALLVERS 

3. Assemble the RSX program ECHOVERS using RMAC: 
RMAC ECHQyERS 

4. Generate a PRL file using the LINK command: 
LINK ECH0UER5 C0P3 

5. Rename the PRL file to an RSX file: 
RENAME ECHOyERS.RSX=ECHOyERS.PRL 

6. Generate a COM file with an anached RSX using the GENCOM command: 
GENCOM CALLVERS ECHOVERS 

7. Run the CALLVERS.COM module: 
CALLVERS 

The message 

*««* CALLVERS **** 

followed by the message 

***» ECHOVERS **** 

appears on the screen five times if the RSX program works. 

End of Section 4 



gJDICTTAL RESEARCH" 



n 
n 
n 

r 



n 
n 
n 



Appendix A 
System Control Block 



The System Control Block (SCB) is a CP/M 3 data structure located in the BDOS. 
CP/M 3 uses this region primarily for communication between the BDOS and the 
BIOS. However, it is also available for communication between application pro- 
grams, RSXs, and the BDOS. Note that programs that access the System Control 
Block are not version independent. They can run only on CP/M 3. 



The following list describes the fields of the SCB that are available for access by 
application programs and RSXs. The location of each field is described as the offset 
from the start address of the SCB [see BDOS Function 49). The RW/RO column 
indicates if the SCB field is Read-Write or Read-Only. 



Table A-1. SCB Fields and Definitions 



Off,a 


RWIRO 


1 Definition 


00 — 04 


RO 


Reserved for system use. 


05 


RO 


BDOS Version Number. 


06 — 09 


RW 


Reserved for user use. Use these four bytes for your 
own flags or data. 


OA — OF 


RO 


Reserved for system use. 


10 — 11 


RW 


Program Error Return Code. This 2-byte field can be 
useti by a program to pass an error code or value to a 
chained program. CP/M 3's conditional command facil- 
ity also uses this field to determine if a program exe- 
cutes successfully. The BDOS Funaion 108 (Get/Set 
Program Return Code) is used to get/set this value. 


12 — 19 


RO 


Reserved for system use. 



m DIGITAL RESEARCH'" - 



A System Control Block CP/M 3 Programmer's Guide 

Table A-1. (continued) 



Offset RW/RO Definition 



RW Console Width. This byte contains the number of col- 

umns, characters per line, on your console relative to 
zero. Most systems default this value to 79. You can 
set this default value by using the GENCPM or the 
DEVICE utility. The console width value is used by the 
banked version of CP/M 3 in BDOS function 10, 
CP/M 3's console editing input function. Note that typ- 
ing a character into the last position of the screen, as 
specified by the Console Width field, must not cause 
the terminal to advance to the next tine. 

RO Console Column Position, This byte contains the cur- 

rent console column position. 

RW Console Page Length. This byte contains the page length, 

lines per page, of your console. Most systems default 
this value to 24 lines per page. This default value may 
be changed by using the GENCPM or the DEVICE util- 
ity (see the CPIM Plus (CPIM Version 3) Operating 
System User's Guide). 

RO Reserved for system use. 

RW Redirection flags for each of the five logical character 

devices. If your system's BIOS supports assignment of 
logical devices to physical devices, you can direct each 
of the five logical character devices to any combination 
of up to 12 physical devices. The 16-bit word for each 
device represents the following: 

Each bit represents a physical device where bit 15 cor- 
responds to device zero and bit 4 corresponds to device 
11. Bits zero through 3 are reserved for system use. 
You can redirect the input and output logical devices 
with the DEVICE command (see CP/M Plus (CP/M 
Version 3) Operating System User's Guide). 



-e DIGITAL RESEARCH'" 



CP/M 3 Programmer's Guide 



A System Control Block 



Table A-1. (continued) 



Offset 


RW/RO 


Definition 


22- 


23 


RW 


CONIN Redirection Flag. 


24- 


25 


RW 


CONOUT Redirection Flag. 


26- 


27 


RW 


AUXIN Redireaion Flag. 


28- 


29 


RW 


AUXOUT Redirection Flag. 


2A- 


-2B 


RW 


LSTOUT Redirection Flag. 


2C 




RW 


Page Mode. If this byte is set to zero, some CP/M 3 
utilities and CCP built-in commands display one page 
of data at a time; you display the next page by pressing 
any key. If this byte is not set to zeto, the system dis- 
plays data on the screen without stopping. To stop and 
start the display, you can press CTRL-S and CTRL-Q, 
respectively. 


2D 




RO 


Reserved for system use. 


2E 




RW 


Determines if CTRL-H is interpreted as a rub/del char- 
acter. If this byte is set to 0, then CTRL-H is a back- 
space character (moves back and deletes). If this byte is 
set to OFFH, dien CTRL-H is a rub/del character, echoes 
the deleted character. 


2F 




RW 


Determines if rub/del is interpreted as CTRL-H charac- 
ter. If this byte is set to 0, then rub/del echoes die deleted 
character. If this byte is set to OFF, then rub/del is inter- 
preted as a CTRL-H character (moves back and deletes). 


30- 


32 


RO 


Reserved for system use. 


33- 


34 


RW 


Console Mode. This is a 16-bit system parameter that 
determines the action of certain BDOS Console I/O 
functions. {See Section 2.2.1 and BDOS Function 109, 
Get/Set Console Mode, for a thorough explanation of 
Console Mode.} 



m DIGITAL RESEARCH'" 



A System Control Block 



CP/M 3 Programmer's Guide 



Table A-1. (continued) 



Offset 


RWIRO 


Definition 


35 — 36 


RO 


Reserved for system use. 


37 


RW 


Output delimiter character. The default output delim- 
iter character is $, but you can change this value by 
using the BDOS Function 110, Get/Set Output Delimiter. 


38 


RW 


List Output Flag. If this byte is set to 0, console output 
is not echoed to the list device. If this byte is set to 1 
console output is echoed to the list device. 


39 — 3B 


RO 


Reserved for system use. 


3C — 3D 


RO 


Current DMA Address. This address can be set by BDOS 
Function 26 (Set DMA Address). The CCP initializes 
this value to 0080H. BDOS Function 13, Reset Disk 
System, also sets the DMA address to 0080H. 


3E 


RO 


Current Disk. This byte contains the currently selected 
default disk number. This value ranges from 0-15 cor- 
responding to drives A-P, respectively. BDOS Function 
25, Return Current Disk, can be used to determine the 
current disk value. 


3F — 43 


RO 


Reserved for system use. 


44 


RO 


Current User Number. This byte contains the current 
user number. This value ranges from 0-15. BDOS Func- 
tion 32, Set/Get User Code, can change or interrogate 
the currently active user number. 


45 — 49 


RO 


Reserved for system use. 


4A 


RW 


BDOS Multi-Sector Count. This field is set by BDOS 
Function 44, Set Multi-Sector Count. 



iS DIGITAL RESEARCH™ 



A System Control Block 



Table A-1. (continued) 



Offset 



Definition 



n 
n 
n 

n 



BDOS Error Mode. This field is set by BDOS Function 
45, Set BDOS Error Mode. 

If this byte is set to OFFH, the system returns to the 
current program without displaying any error messages. 
If it is set to OFEH, the system displays error messages 
before returning to the current program. Otherwise, the 
system terminates the program and displays error mes- 
sages. See description of BDOS Function 45, Set BDOS 
Error Mode, for discussion of the different error modes. 

Drive Search Chain. The first byte contains the drive 
numbet of the first drive in the chain, the second byte 
contains the drive number of the second drive in the 
chain, and so on, for up to four bytes. If less than four 
drives are to be searched, the next byte is set to OFFH 
to signal the end of the search chain. The drive values 
range from 0-16, where corresponds to the default 
drive, while 1-16 corresponds to drives A-P, respec- 
tively. The drive search chain can be displayed or set 
by using the SETDEF utility (see CP/M Plus (Version 3) 
Operating System User's Guide). 

Temporary File Drive. This byte contains the drive 
number of the temporary file drive. The drive number 
ranges from 0-16, where corresponds to the default 
drive, while 1-16 corresponds to drives A-P, respectively. 



Error drive. This byte contains the drive number of the 
selected drive when the last physical or extended error 
occurred. 

Reserved for system use. 



i DIGITAL RESEARCH™ 



CP/M 3 Programmer's Guide 



Table A-1, (continued) 



Off$et 1 


RW/RO 


Definition 


57 


RO 


BDOS Flags. Bit 7 applies to banked systems only. If 
bit 7 is set, then the system displays expanded error 
messages. The second error line displays the function 
number and FCB information. (See Section 2.3.13). 
Bit 6 applies only to nonbanked systems. If bit 6 is set, 
it indicates that GENCPM has specified single alloca- 
tion veaors for the system. Otherwise, double alloca- 
tion vectors have been defined for the system. Function 
98, Free Blocks, returns temporarily allocated blocks to 
free space only if bit 6 is reset. 


58 — 59 


RW 


Date in days in binary since 1 Jan 78. 


5A 


RW 


Hour in BCD (2-digii Binary Coded Decimal). 


5B 


RW 


Minutes in BCD. 


5C 


RW 


Seconds in BCD. 


5D — 5E 


RO 


Common Memory Base Address. This value is zero for 
nonbanked systems and nonzero for banked systems. 


5F — 63 


RO 


Reserved for system use. 



End of Appendix A 



- m DIGITAL RESEARCH™ 



Appendix B 
PRL File Generation 



B.l FRL Format 

A Page Relocatable Program has an origin offset of lOOH bytes that is stoted c 
disk as a file of type PRL. The fotmat is shown in Table B-1. 





Tabic B-1. PRL File Format 


Address \ 


Contents 


0001-0002H 


Program size 


0004-OOOSH 


Minimum buffer requirements (additional memory} 


0006-OOFFH 


Currently unused, reserved for future allocation 


0100 + Program 


size = Start of bit map 



The bit map is a string of bits identifying those bytes in the source code that 
require relocation. There is one byte in the bit map for every 8 bytes of source code, 
The most significant bit, bit 7, of the first byte of the bit map indicates whether or 
not the first byte of the source code requires relocation. If the bit is on, it indicates 
that relocation is required. The next bit, bit 6, of the first byte corresponds to the 
second byte of the source code, and so forth. 



m DIGITAL RESEARCH™ 



B PRL Generation CP/M 3 Programmer's Guide 

B.2 Generating a PRL 

The preferred technique for generating a PRL file is to use the CP/M LINK-SO"", 
which can generate a PRL file from a REL relocatable objea file. This technique is 
described in the Programmer's Utilities Guide for The CP/M Family of Operating 
Systems. A sample link command is shown below. 

A> J in/( duMpCopJ 



End of Appendix B 



@ DIGITAL RESEARCH'" 



n 



Appendix C 
SPR Generation 



System Page Relocatable, SPR, files are similar in format to PRL files except that 
SPR files have an origin offset of OOOOH (see Appendix B). SPR Files are provided as 
part of the standard CP/M 3 System; the resident and banked portions of the banked 
BDOS, named RESBD0S3.SPR and BNKBDOS3.SPR, and the nonbanked BDOS, 
named BD0S3.SPR. The customized BIOS must also be generated in SPR format 
before GENCPM can create a CP/M 3 system. The BIOS SPR file is named 
BNKBIOS3.SPR for banked systems and BIOS3.SPR for nonbanked systems. A detailed 
discussion of the generation of BIOS3.SPR or BNKBIOS3.SPR is provided in the 
CP/M Plus (CP/M Version 3) Operating System System Guide. 

The method of generating an SPR is analogous to that of generating a Page Relo- 
catable Program (described in Appendix B) with the following exceptions: 

■ If LlNK-80 is used, the output file of type SPR is specified with the [os] or [b] 
option. The [b] option is used when linking BNKBIOS3.SPR. 

■ The code in the SPR is ORGed at OOOH rather than lOOH. 



End of Appendix C 



m DIGITAL RESEARCH'" - 



n 
n 



Appendix D 
ASCII and Hexadecimal Conversions 



This appendix contains tables of the ASCII symbols, including their binary, deci- 
mal, and hexadecimal conversions. 





Table D-1. 


ASCn Symbols 




Symbol 


Meaning 


Symbol \ 


Meaning 


ACK 


acknowledge 


FS 


file separator 


BEL 


bell 


GS 


group separator 


BS 


backspace 


HT 


horizonral tabulation 


CAN 


cancel 


LF 


line-feed 


CR 


carriage return 


NAK 


negative acknowledge 


DC 


device control 


NUL 


null 


DEL 


delete 


RS 


record separator 


DLE 


data link escape 


SI 


shift in 


EM 


end of medium 


SO 


shift out 


ENQ 


enquiry 


SOH 


start of heading 


EOT 


end of transmission 


SP 


space 


ESC 


escape 


STX 


start of text 


ETB 


end of transmission 


SUB 


substitute 


ETX 


end of text 


SYN 


synchronous idle 


FF 


form-feed 


US 


unit separator 






VT 


vertical tabulation 



D ASCII and HEX Conversions 



CP/M 3 Programmer's Guide 





Table D-2. 


ASCn Conversion Table 






Binary 


1 Decimal 


Hexadecimal | 




ASCII 


0000000 


000 


00 


NUL 




0000001 


001 


01 


SOH (CTRL-A) 1 


0000010 


002 


02 


STX 


(CTRL-B) 


0000011 


003 


03 


ETX 


(CTRL-C) 


0000100 


004 


04 


EOT (CTRL-D) 


0000101 


005 


05 


ENQ (CTRL-E) 


0000110 


006 


06 


ACK (CTRL-F) 


0000111 


007 


07 


BEL 


(CTRL-G) 


0001000 


008 


08 


BS 


(CTRL-H) 


0001001 


009 


09 


HT 


(CTRL-1) 


0001010 


010 


OA 


LF 


(CTRL-J) 


0001011 


Oil 


OB 


VT 


(CTRL-K) 


0001100 


012 


OC 


FF 


(CTRL-L) 


0001101 


013 


OD 


CR 


(CTRL-M) 


0001110 


014 


OE 


SO 


(CTRL-N) 


0001111 


OlS 


OF 


SI 


(CTRL-O) 


0010000 


016 


10 


DLE 


(CTRL-P) 


0010001 


017 


11 


DCl 


(CTRL-Q) 


0010010 


018 


12 


DC2 


(CTRL-R) 


0010011 


019 


13 


DC3 


(CTRL-S) 


0010100 


020 


14 


DC4 


(CTRL-T) 


0010101 


021 


15 


NAK (CTRL-U) 


0010110 


022 


16 


SYN 


(CTRL-V) 


0010111 


023 


17 


ETB 


(CTRL-W) 


oouooo 


024 


18 


CAN(CIRL-X) 1 


0011001 


025 


19 


EM 


(CTRL-Y) 


0011010 


026 


lA 


SUB 


(CTRL-Z) 


OOllOIl 


027 


IB 


ESC 


(CTRL-t) 


0011100 


028 


IC 


FS 


(CTRL-\) 


OOIIIOI 


029 


ID 


GS 


(CTRL-J) 


0011110 


030 


IE 


RS 


(CTRL--) 


0011111 


031 


IF 


US 


(CTRL- ) 


0100000 


032 


20 


(SPACE) 1 


0100001 


033 


21 


! 




0100010 


034 


22 






0100011 


035 


23 


# 




0100100 


036 


24 


{ 





- SJ DIGITAL RESEARCH™ 



H, CP/M 3 Programmer's Guide 



D ASCII and HEX Conversions 





Table D-2. 


(condnued) 




Binary 


Decimal | 


Hexadecimal [ 


ASCII 


0100101 


037 


25 


% 


0100110 


038 


26 


8c 


0100111 


039 


27 




0101000 


040 


28 




0101001 


041 


29 




0101010 


042 


2A 




0101011 


043 


2B 




0101100 


044 


2C 




0101101 


045 


2D 




0101110 


046 


2E 




0101111 


047 


2F 




0110000 


048 


30 




0110001 


049 


31 




0110010 


050 


32 




0110011 


051 


33 




0110100 


052 


34 




0110101 


053 


35 




0110110 


054 


36 




0110111 


055 


37 




0111000 


056 


38 




0111001 


057 


39 




0111010 


058 


3A 




OUlOU 


059 


3B 




0111100 


060 


3C 




0111101 


061 


3D 




0111110 


062 


3E 




0111111 


063 


3F 




1000000 


064 


40 


® 


1000001 


065 


41 


A 


1000010 


066 


42 


B 


1000011 


067 


43 


C 


1000100 


068 


44 


D 


1000101 


069 


45 


E 


1000110 


070 


46 


F 


1000111 


071 


47 


G 


1001000 


072 


48 


H 


1001001 


073 


49 


I 



i DIGITAL RESEARCH"'- - 



D ASCII and HEX Con' 



CP/M 3 Programmer's Guide 





Table D-2. 


(continued) 




Binary 


Decimal | 


Hexadecimal 


ASCII 


1001010 


074 


4A 


] 


1001011 


075 


4B 


K 


1001100 


076 


4C 


L 


1001101 


077 


4D 


M 


1001110 


078 


4E 


N 


1001111 


079 


4F 


O 


1010000 


080 


SO 


P 


1010001 


081 


51 


Q 


1010010 


082 


52 


R 


1010011 


083 


53 


S 


1010100 


084 


54 


T 


1010101 


085 


55 


U 


1010110 


086 


56 


V 


1010111 


087 


57 


W 


1011000 


088 


58 


X 


1011001 


089 


59 


Y 


1011010 


090 


5A 


Z 


1011011 


091 


SB 




1011100 


092 


5C 




1011101 


093 


5D 




1011110 


094 


5E 




1011111 


095 


5F 




1100000 


096 


60 




1100001 


097 


61 




1100010 


098 


62 




1100011 


099 


63 




1100100 


100 


64 




1100101 


101 


65 




1100110 


102 


66 





CP/M 3 Programmer's Guide 



D ASCII and HEX Conversions 





Table D-2. 


(continued) 




Binary | 


Decimal | 


Hexadecimal 


ASCII 


1100111 


103 


67 


S 


1101000 


104 


68 


h 


1101001 


105 


69 


i 


1101010 


106 


6A 


i 


1101011 


107 


6B 


k 


1101100 


108 


6C 


1 


1101101 


109 


6D 


m 


1101110 


110 


6E 


n 


1101111 


111 


6F 





1110000 


112 


70 


P 


1110001 


113 


71 


q 


1110010 


114 


72 




1110011 


115 


73 


s 


1110100 


116 


74 


t 


1110101 


117 


75 


u 


mono 


118 


76 


V 


1110111 


119 


77 


w 


1111000 


120 


78 


X 


1111001 


121 


79 


y 


UUOIO 


122 


7A 


z 


1111011 


123 


7B 


{ 


1111100 


124 


7C 


1 


1111101 


125 


7D 


} 


1111110 


126 


7E 


- 


1111111 


127 


7F 


DEL 



End of Appendix D 



m DIGITAL RESEARCH'- 



Appendix E 
BDOS Function Summary 

Table E-1. BDOS Function Summary 



Function 


pMMCd'on Hame 


Input Parameters 


j Returned Values 





System Reset 


none 


none 




Console Input 


none 


A . char 




Console Output 


E - char 


A = OOH 




Auxiliary Input 


none 


A - char 




Auxiliary Output 


E = char 


A = OOH 




List Output 


E = char 


A = OOH 


6 


Direct Console I/O 


E - OFFH/ 


A = char/status/ 






OFEH/ 


none 






OFDH/ 








char 




7 


Auxiliary Input 
Status 


none 


A - OO/OFFH 


8 


Auxiliary Output 
Status 


none 


A = OO/OFFH 


9 


Print String 


DE = .String 


A = OOH 


10 


Read Console Buffer 


DE = .BufferO 


Characters in buffer 


11 


Get Console Status 


none 


A = 00/01 


12 


Return Version Number 


none 


HL = Version (0031H) 


U 


Reset Disk System 


none 


A = OOH 


14 


Select Disk 


E = Disk 
Number 


A = Err Flag 


15 


Open File 


DE = .FCB 


A - Dir Code 


16 


Close File 


DE - .FCB 


A = Dir Code 


17 


Search for First 


DE = .FCB 


A - Dir Code 


IS 


Search for Next 


none 


A = Dir Code 


19 


Delete File 


DE = .FCB 


A = Dir Code 


20 


Read Sequendal 


DE - .FCB 


A = Err Code 


21 


Write Sequential 


DE = .FCB 


A = Err Code 


22 


Make File 


DE = .FCB 


A = Dir Code 


23 


Rename File 


DE . .FCB 


A = Dir Code 


24 


Return Login Veaor 


none 


HL = Login Veaor 


25 


Return Current Disk 


none 


A - Cur Disk# 



ipl DIGITAL RESEARCH'" 



E BDOS Function Summary 



CP/M 3 Programmer's Guide 





Table E-1. (continued) 




Function 


Function Name 


Input Parameters 


Returned Values 


Z5 


Return Current Disk 


none 


A - Cur Disk* 


26 


Set DMA Address 


DE - .DMA 


A = OOH 


27 


Get Addr(Alloc) 


none 


HL = .Alloc 


28 


Write Protea Disk 


none 


A - OOH 


29 


Get R/0 Vector 


none 


HL - R/O Vector 


30 


Set File Attributes 


DE • .FCB 


A - Dir Code 


31 


Get Addt(DPB) 


none 


HL = .DPB 


32 


Set/Get User Code 


E - OFFH/ 


A = Curt User/ 






user number 


OOH 


33 


Read Random 


DE - .FCB 


A - Err Code 


34 


Write Random 


DB = .FCB 


A = Err Code 


35 


Compute File Size 


DE = .FCB 


rO, rl, r2 
A = Err Flag 


36 


Set Random Record 


DE = .FCB 


rO, rl, r2 


37 


Reset Drive 


DE = Drive 
Vector 


A - OOH 


38 


Access Drive 


none 


A - OOH 


39 


Free Drive 


none 


A = OOH 


40 


Write Random with 
Zero Fill 


DE - .FCB 


A - Err Code 


41 


Test and Write Record 


DE - .FCB 


A - OFFH 


42 


Lock Record 


DE = .FCB 


A = OOH 


43 


Unlock Record 


DE - .FCB 


A - OOH 


44 


Set Mulri-seaor Count 


E = # Sectors 


A = Return Code 


45 


Set BDOS Ettot Mode 


E = BDOS Err 
Mode 


A - OOH 


46 


Get Disk Free Space 


E - Drive 


Number of Free Sectors 






number 


A = Err Flag 


47 


Chain to Program 


E = Chain Flag 


A = OOH 


48 


Flush Buffers 


E = Purge Flag 


A . Err Flag 


49 


Get/Set System 


DE - .SOB PB 


A = Returned Byte 




Control Block 




HL - Returned Word 


50 


Direct BIOS Calls 


DE - .BIOS PB 


BIOS Return 


59 


Load Overlay 


DE = .FCB 


A - Err Code 


60 


Call Resident System 
Extension 


DE = .RSX PB 


A = Err Code 



Note: . indicates the address of 



- IS DIGITAL RESEARCH™ 



CP/M i Programmer's Guide 



E BDOS Function Summary 





Table E-1. (continued) 




Function 


1 Function Name 


Input Parameters 


Returned Values 


98 


Free Blocks 


none 


A = Err Flag 


99 


Truncate File 


DE - .FCB 


A - Dir Code 


100 


Set Directoty Label 


DE = .FCB 


A = Dir Code 


101 


Return Directory 
Label Data 


E = Drive 


A = Dir label data byte 


102 


Read File Date Stamps 
and Password Mode 


DE - .FCB 


A = Dir Code 


103 


Write File XFCB 


DE = .FCB 


A = Dir Code 


104 


Set Date and Time 


DE - .DAT 


A = OOH 


105 


Get Date and Time 


DE = .DAT 


Date and Time 
A = seconds 


106 


Set Default Password 


DE = .Password 


A = OOH 


107 


Return Serial Number 


DE - .Serial # 
lield 


Serial Number 


108 


Get/Set Program 


DE = OFFFFH/ 


HL Program Ret Code 




Return Code 


Code 


none 


109 


Get/Set Console Mode 


DE = OFFFFH/ 


HL - Console Mode 






Mode 


none 


110 


Get/Set Output 


DE = OFFFFH/ 


A = Output Delimiter 




Delimiter 


E = Delimiter 


none 


HI 


Print Block 


DE = .CCB 


A . OOH 


112 


Ust Block 


DE - .CCB 


A = OOH 


152 


Parse Filename 


DE = .PFCB 


See definition 



Note: . indicates the address of 



End of Appendix E 



m DIGITAL RESEARCH " 



Index 



7 in filsnane error, 2-30 
555 filetype, 1-27 



absolute module, 3-73 

I date and time stanp, 3-21 

■ i stamp types, 2-24 

ACCESS DRIVE, 3-57 

address, maximuKin, 1-5 
^ allocation vector, 2-27, 

I J 3-41, 3-75 

ambiguous file reference, 
1-13, 2-16, 3-24, 3-27 
^- archive attribute, 2-17 
' i ASCII character file, 1-18 

ASM- , 2-11 

assembler source, 2-11 

associated command files, 1-18 
'"' asterisk, 1-13, 2-11 

I attribute bits, 2-16 

■ ' attributes 

set file, 2-22 
cq automatic submit, 1-19 

I ] Auxiliary Input, 3-4 

. 1 Auxiliary Input Status, 3-9 

Auxiliary Output, 3-5 
Auxiliary Output Status, 3-10 
'- AUXIN, 2-2, 2-6, 3-4, 3-9 

I AUXOUT, 2-2, 2-6, 3-5, 3-10 



backspace, 3-2 
BAK, 2-11 
Bank 0, 1-3 

in context, 1-3 
~ switched in, 1-3 

Bank 1, 1-3, 1-4 
banked, 1-2, 1-11 
memory, 1-3 
— operating system module, 1-3 

system, 1-3 

version requirements, 1-5 
bank -switching, 1-4 
bank -switched memory, 1-1, 1-3 
"~ HAS, 2-11 

base address, 1-21 
base extent, 3-48, 3-50 
basic console l/O, 2-3 



Basic Disk Operating System 

See BDOS 
Basic Input/Output System 

See BIOS 
basic record size, 2-7 
BDOS, 1-6, 1-8, 1-11, 1-14 
calling conventions, 2-1 
Call Resident System 

Extension (HSX), 1-24 
chain to program call, 1-23 
directory codes, 2-32 
directory functions, 2-7 
drive-related functions, 2-7 
error codes, 2-31 
error flags, 2-33 
error mode, 2-29 
extended error codes, 2-34 
file access functions, 2-7 
file system, 2-7, 2-11 
miscellaneous funct ions, 2-7 
physical errors, 2-34 
read character, 2-3 
write character, 2-3 
BDOSbase, 1-8 to 1-11 
bell character, 3-12 
binary zero terminator, 3-12 
BIOS, 1-6, 1-7, 1-14, 2-29 
cold start, 1-15 
DEVTBL entry point, 2-2 

Parameter Block, 3-72 

warm start, 1-15 
B10S_base, 1-8, 1-10, 1-15 
BIOSPS, 3-72 
bit map, B-1 
bit vector, 3-43 
blocking, record, 3-63 
block size, 2-11 
Boolean fields, 2-16 
buffers, 1-4 

disk, 1-2 
built-in command, 1-S, 1-16 
byte, 2-1 
byte count, 2-28 



Call BIOS, 1-22 
Call Resident System 

Extension (RSX), 3-74 



calling program, 2-15 
return to, 2-28 

carriage return, 2-13, 3 

CCB, 3-94, 3-95 

CCP 

description 1-7, 1-8, 

1-11, 1-13 
location, 1-6, 1-15 
operation, 1-16 to 1-2 
user number, 2-18 

CCP.COM, 1-15 

CCP command form, 1-16 

chain flag, 3-67 

Chain To Program, 3-67 

change default drive, 1- 

character block, 2-2 

Character Control Block 
See CX:b 

character echo, 2-3 

character string, 2-2 






-27 



Close File, 2-17, 3-22 
cold boot, 1-14 
Cold Boot Loader, 1-14 
cold start, 1-14, 1-15, 
COM, 2-11 

filetype, 1-19 
command, 

drive field, 2-37 

field, 1-20 

keyword, 1-17 
Command Pile, 2-11 
command line, 1-17 

characters, 2-38 



region, 1-3 
common region, 1-3 

size, 1-5 
compatibility, 1-22, 1-28 
compatibility between CP/M 3 

and MP/M, 3-61, 3-62 
Compute File Size, 2-28, 3-53 
conditional command, 1-23 
conditional status, 2-6 
configured memory size, 1-7 
CONIN, 1-7, 2-2, 2-3, 3-2, 3-l( 
CONOUT, 2-2, 2-3, 3-3 

bloc)( output, 2-3 
characteristics, 1-27 
column position, 3-70 
I/O functions, 2-3 



input, : 


2-3, 3 


-2 


output. 


2-3, 


3-3 


page lei 


ngth. 


3-70 


sitatus. 


2-3, 


3-8 


string < 


autput 


, 2-3 


width, . 


3-70 




Console Command 


Process! 


See CCP 






Console Input, 


3-2 


Console Mode, 2- 


-5, 3-91 


de fault 


state 


, 3-2 


Console Output, 


3-3 


control character ("), : 


COPY, 4-1 






c opy f i le , 


, 1-12 


, 4-1 


CP/M, 1-1, 


, 1-2 




CP/M 2, 1- 


-28, 2 


-1 


CPM3.SY-S 


file, : 


1-14 


CPMLDR, 1- 


-14, 1 


-15 


CPMLDR BDOS, 1- 


14 


CPU regis! 


ters. 


1-22 


cr field. 


3-29, 


3-31, 3- 



date and tii 



ectory label, 3-78 



3tanT> 


type 




2-24 


XFCB, 


3-34 






CTRL- A, 


3-14 






CTHI>B, 


3-14 






CTRL-C, 


1-22 




2-4, 2-5 


3-13, 3- 


14 




reboot, 3-. 


L3 




CTRL-E, 


3-13 


, 3-14, 3- 




E lin. 




3-13 


CTHL-F, 


3-14 






CTRL-G, 


2-4, 


3- 


-14 


CTRL-H, 


3-2, 


3- 


-13, 3-1. 


backspace, 


3- 


-13 


CTRL- I, 


3-2, 


3- 


-3 


CTRl^J, 


3-13 


, 3-15 


Line : 


feed. 


3- 


-13 


CTRL-K, 


3-15 






CTRL-M, 


3-13 


, 3-15 


CTRL-P, 


2-4, 


2- 


-5, 3-2, 


3-13, 3- 


15 




list devic 


e. 


3-13 


CTHL-Q, 


2-4, 


2- 


-5, 3-2, 


CTRL-R, 


3-13 


, 3-15 


retype lin. 




3-13 


CTRL-S, 


2-4, 


2- 


-5, 3-2, 


CTHL-O, 


3-13 


, 3-15 



CTRL-W, 3-15 



CTRL-X, 3-13, 3-15 

beginning of line, 3-13 
CTRL-Z, 2-3, 2-13 
curly brackets, 3-96 
current record, 2-15 
current record field of the 

FCB, 3-20 
current record position, 2-36 
current user number, 1-28 



DAT, 2-11, 3-85 

area, 1-12, 1-13, 2-12 
block, 2-11, 2-12, 3-75 

data base nanagenent system, 
4-19 

Data File, 2-11 

ctory area, 1-12 



dati 



1-12 



date . 

2-23, 2-25, 3-35,' 
3-81, 3-85 
DATE utility, 2-25 
de fau It 

disk, 1-15, 3-19 

CMA buffer, 2-35 

drive, 1-16, i-28 

FCB, 2-37 

mode, 3-64 

output delimiter, 3-93 

password, 2-23, 3-87 
Default Error Mode, 3-64 
Delete File, 2-17, 2-22, 3-27 
delimiter, 1-17, 2-10, 
3-11, 3-93 

file specification, 3-97 
DEVICE utilitY. 2-2 
differences: banked and 

nohbanked, 1-2 
DIR, 1-18 

DIR.COM utility, 1-18 
Direct BIOS Calls, 1-22, 3-72 
Direct Console I/O, 3-7 
Direct Memory Address 

(DMA), 3-40 
directory 

area, 1-12 

check-aum vector, 2-27 

codes, 2-30, 2-32 

entries, 2-15 



functions, 2-8 

hash tables, 1-2, 1-4 

apace, 1-13 
directory label, 2-19, 2-20, 

create, 3-78 

data byte definition, 
3-78, 3-80 

password, 2-21 

update, 3-78 
DIRLBL.RSX, 1-25, 2-21, 3-78 
DIRSYS, 1-18 
disk, 1-11 

access, 1-12 

change, 2-27 

current, 3-71 

default, 1-15, 3-19 

directory area, 2-12 

drive organization, 1-12 

formatting program, 1-22 

I/O error, 2-28, 2-29 

record buffers, 1-2, 1-4 

select, 2-29 

space, 1-13 
Disk Parameter Block 

(DPS), 3-46 
Disk Reset, 2-27 
DMA, 3-40 

address, 3-71 

buffer, 2-35 

default address, 2-38 
DPB (Disk Parameter 
Block), 3-46 

access, 3-57 

allocation vector, 2-27 

capacity, 2-12 

chain, 1-20 

code, 2-14 

default, 1-16, 1-28 

functions, 2-8 

read-only, 3-43 

reset, 3-56 

search chain, 3-71 

select code, 2-9, 

specification, 1-17, 1-20 

specifier, 2-9 

support, 1-11 
dr ive-related functions, 

2-7, 2-8 
dump program, 4-5 
dynamic allocation, 1-13 



;d Source Backup, 2-11 
id it control characters, 
banked CP/M 3, 3-14 
noribanked CP/M 3, 3-13 



ntry 






, 2-1 

1-7 

ERASE, 1-18 

errors, 2-30, 2-31 
? in filename, 2-30 
ex tended, 2-29 , 2-34 
file exists, 2-30 
flag, 2-33 
handling, 2-28 
invalid drive, 2-29 
messages, 2-29, 2-30 
mode, 2-29, 3-64, 3-71 
physical, 2-28, 2-29, 2 
program code, 3-S9 
read-only, 2-30 
return code, 3-70 

extend operating system 
functions, 1-9, 1-23 

extended error codes, 2-21 
2-30, 2-34, 

extended FCB, 2-19 

extent 0, 3-48, 3-50 

extent field format, 3-83 

extent number, 2-14 



false status, 2-6 
FCB, 3-20 

default, 2-36, 2-37 

extent number field, 3-3S 

format, 2-18, 3-98 

length, 2-13 

parsed, 1-21 

random record field, 3-55 
field, 1-19 
file 

access functions, 2-7 

attributes, 2-16 

byte count, 2-28, 3-44 

directory elements, 2-15 

format, 2-13 

identification, 1-12 

organization, 2-11 
passMords, 2-21 
password error, 2-30 



size, 1-12, 2-12, 3-53 
space allocation, 1-13 
specification, 2-9 
types of, 2-11 

file access functions, 2-' 

File Control Block 
See FCB 

default, 2-36 

Fi le Dump, 4-5 

File Exists error, 2-30 

filename, 1-13, 1-17, 2-9 
2-11, 2-15 






2-11 



2-9, 



3-65 



3-2 



3-96 
filespec, 1-17 
filetype, 1-13, 1-17, 

2-11, 2-15 
floppy disk, 1-11 
Flush Buffers, 2-25, 

2-33, 3-68 
Free Blocks, 2-33, 3' 
Free Drive, 3-58 

Function Calls: 
0: System Reset, 
1 : Console Input 
2 : Con so le Ou tpu c , 
3 : Auxiliary Inpu' 
4: Auxiliary Output, 
5: List Output, 3-6 
6: Direct console l/O, 3-7 
7: Auxiliary Input Status, 

3-9 
8: Auxiliary Output Status, 

3-10 
9: Print String, 3-11 
10: Read Console Buffer, 3-12 
Get Console Status, 3-16 
Return Version Number, 
3-17 



3-5 



12: 



Bset Disk Systi 
14: Select Disk, 3- 
15: Open Fi le, 3-20 
16: Close File, 3-2 
17: Search For Firs 
18: Search For Next, 3-26 
19: Delete File, 3-27 
20: Head Sequential, 3-29 
21: Write Sequentia 
22: Make File, 3-34 
23: Rename File, 3-36 
24: Return Login Vector, . 
25: Return Current Disk, : 
26: Set CHA Address, 3-40 
27: Get ADDR(ALLOC), 3-41 



24 



31 



: Write Protect Disk, 3-42 
; Get Read-Cnly Vector, 

3-43 
; Set File Attributes, 3-44 
: Get ADDR{DPB PAIWS ) , 3-46 
; Set/Get User Code, 3-47 
: Read Random, 3-48 
; Write Random, 3-50 

Compute Fiie Size, 3-53 

Set Randora Record, 3-55 

Reset Drive, 3-56 

Access Drive, 3-57 
; Free Drive, 3-58 
. Write Random with Zero 

Fi 1 1 , 3-59 

Te St and Wr ite Reo ord , 

3-60 

LiOCk Record, 3-61 

Unlock Record, 3-62 

Set Multi-Sector Count, 

3-63 

Set BDOS Error Mode, 3-64 

Get Disk Free Space, 3-65 

Qiain To Program, 3-67 

Flush Buffers, 3-68 

Get/Set System Control 

Block, 3-69 

Direct BIOS Calls, 3-72 
. Load Overlay, 3-73 

Call Resident System 

Extension, 3-74 

Free Blocks, 3-75 
. Truncate File, 3-76 



GENCOM, 1-9, 1-24, 2-6 

GENCPM, 1-2, 1-16 

generic filetypea, 2-11 

Get 

ADDR(ALLOC), 2-34, 3-41 
ADDR(DPB PABMS), 3-46 
.COM, 1-24, 1-26 
Console Status, 3-16 



Dat( 



and Tim 



Disk Free Space, 2-33, 

3-41, 3-65 
Output Delimiter, 3-93 
Program Return Code, 3-89 
Read-only Vector, 3-43 
RSX, 2-6 
• RSX, 1-24 
User Code, 3-47 
utility, 1-24, 1-26 

Get/Set 

Console Mode, 2-5, 3-91 
Output Delimiter, 3-93 
Program Return Code, 

1-23, 3-89, 3-90 
System Control Block, 3-69 
User Code, 3-47 

graphic characters, 3-2 



100! 


Set directory Label, 






3-78 


hash table, 1-4, 2-27 


lOlj 


Return Directory Label 


directory, 1-2 




Data, 3-80 


HEX, 2-11 


102: 


Read File Cete Stands 


Hex [techine Code, 2-11 




and Password Mode, 3-81 


highest memory address, 2-3 


103: 


Write File XFCB, 3-83 


host oonputer's environment 


104: 


Set Date and Time, 3-85 


1-7 


105: 


Get CBte and Time, 3-86 




106: 


Set Default Password, 

3-87 

Return Serial Number, 


I 


107: 


information address, 2-1 




3-88 


INITDIR utility, 2-24, 3-79 


108 1 


Get/Set Program Return 


initializing an FCB, 2-15 




Code, 3-89 


input buffer, 3-12 


109: 


Get/Set Console (t>de. 


INT, 2-11 




3-91 


Intel* PL/M systems programn 


110: 


Get/Set Output 


language, 2-1 




Delimiter, 3-93 


interface attribute, 2-17, 


111! 


Print Block, 3-94 


Intermediate File, 2-11 



internal date and i 
Invalid Drive erro: 
invalid function c; 



key fields, 3-55 



length, 1-21, 2-23 
line editing, 2-4 
line feed, 2-13, 3-2 
LINK-aO" , B-2 
List Block, 3-95 
list device, 2-4, 3-2 
List Output, 3-6 
LOADER_base, 1-9, 1-11 
LOADER module, 1-6, 1-9, 1-11 
1-21, 1-23, 1-24, 
3-73, 4-21 
Load Overlay, 1-9, 1-24 
load RSX, 1-9, 1-24 
Lock Record, 3-61 

MP/M, 3-61 
logged-in, 2-27 
logical, 

auxiliary input devic 

auxiliary output devi 

AUXm, 2-2 

AUXOUT, 2-2 

CONIN, 2-2 

CONOUT, 2-2 

console input device, 

nsole output device, 2-2 



73 



2-2 






2-2 



drive, 1-11, 2-11, 
list device, 3-6 
list output device, 
LSr, 2-2 

memory organizat ior 
record size, 2-25 

LSr, 2-4, 2-6 

LST:, 3-2, 3-6, 3-95 



2-12 



file size, 2-11 
niemory, 1-2 
memory address, 1-10 
record count, 3-53 
TPA address, 1-21 
med ia change, 2-27 

banked, 1-3 
base address, 1-10 
loading, 1 -14 
logical, 1-5 

maximum, 1-2 
minimum. 1-2 
organization, 1-i, 1-2 
regions, 1-9, 1-10 
size configured, 1-7 
space, 1-2 
top of, 1-10 



ellani 



fure 



modify file attribute, 3-44 
operating system 

functions, 1-9, 1-24 
other functions, 2-5 
modules, 1-6 

of operating system, 1-5 
MP/M, 1-19, 1-2B, 

2-1, 3-17 
multi-sector count, 2-26, 

3-29, 3-63, 3-71 
Multi-Sector I/O, 2-26 
multi-user operating system, 

1-19, 1-28 
multiple file reference, 1-13 



next record, 3-55 

nibble, 1-28 

nonbanked memory organ iz at ioi 

1-2 
nonbanked systems, 1-1 
nonsupported function number 

2-1 



OFFSET parameter, 3-69 
Open File, 2-16, 3-20 
operating system modules 

banked, 1-3, 

resident, 1-3 



3-70, 3-93 



page, 

alignment, 1-10 
boundaries, 1-10 
mode, 3-70 
Page Relocatable file, 1-19, 

1-24, 2-11 
Page Zero, 1-6, 1-7, 1-15, 
1-21, 1-22, 1-25, 1-28 



2-35 
fields, 1-21, 



printer echo, 2-4, 2-5, 3-2 

printer list ing, 2-11 
Print String, 3-11 
PRL file, 1-19, 1-24, 

2-11, 3-73 
PBL File Format, B-1 
PRN, 2-11 

PROFILE, SUB, 1-15 
PROFILE submit file, 1-15 
program chain, 1-23, 3-67 
Program Return Code, 

1-23, 3-89 
PUNCH, 2-6 
Purge Flag, 3-68 



aliz 



par; 
par. 



interface, 1-28 
irameter Block 
BIOS, 3-7 2 
RSX, 3-74 
SCB, 3-69 

subst ita< 



1-15, 2-34 ■ 



1-27 



icedure, 1-19 
parsed FCB, 1-21 
Parse Filename, 3-96 
Partial Close, 2-17, 3-22 
passw ord , 1-17, 1 -20 , 
2-21, 3-83, 

assign, 2-17 

default, 2-23, 3-87 

field, 2-9, 2-10, 2-35 

length, 2-23, 2-35, 2-36 

mode, 3-81 

protection, 1-13, 2-22, 3-33, 
3-34, 3-87 

support, 1-1 

testing, 2-22 
Password Protection Modes, 2-22 
permanent close operation, 3-22 

drive, 1-11 

error, 2-29, 3-33 

error codes, 2-34, 3-19, 
3-21, 3-25 

file size, 3-53 

memory, 1-2 

record size, 2-25 

write operations, 2-25 
PIP command, 1-12 
PIP utility, 2-17 
PL/I Source File, 2-11 
PL/M, 2-1 
Print Block, 2-3, 3-94 



lark, 1-13, 2-11 



RANDOM, 4-10 

random 

access program, 4-10 

access processing, 4-11 

file, 2-12 

record, 3-55 

record number, 2-12, 2-15 

record position, 2-36 

character, 3-2 

edited console input, 3-12 

file date stands and pasawoi 
mode, 3-81 

next record, 3-29 
Read Buffer Input, 2-4 
Read Console Buffer, 3-12 
READER, 2-6 
Read Fi le Cate Stands and 

Password Mode, 3-81 
Read-Cnly, 3-42 

attribute, 2-16 

Disk error, 2-30 

drives, 3-43 



File en 



2-30 



Prii 



Str 



ng, 



2-3, 2-5, 3-11 



Read Random, 2-30, 
Read Sequential, 2-30, 

3-29, 3-48 
Read-Write, 3-42 
record, 2-12, 3-60 
blocking, 2-25, 3-63 
count, 2-14 
deblocking, 2-25 
lock, MP/M, 3-61 
size, 2-7 



teat, 3-60 


s 




unlock, MP/M, 3-62 






write, 3-60 


SCB, 1-27, 1-28, 3-69, 


3-70 


idirected input, 1-27 


SCB parameter block, 3 


1-69 


igion boundaries, 1-9 


scroll, 3-2 




.gister. 


output, 2-4 




A, 2-31 


support, 2-5 




entry values, 2-1 


Search, 2-28 





BEL, 2-11 



Reloca 


table Module 


, 2-11, . 


3-7: 


relocation, B-1 






flag 


, 1-26 






last 


character. 


3-13 




RSX, 


1-26 






RENAME 


, 1-18 






Rename 


File, 3-36 






Reset 


Disk System, 


1-22, 3- 


-la 


Reset 


Drive, 2-27, 


3-lS, 3- 


-56 


reside 


nt operating 


system 




module, 1-3 






reside 


nt portion. 


1-3 




Resident System Ex 


tension 




Se 


e RSX 






Reside 


nt System Extension 




program, 4-20 






Return 








Curr. 


ent Disk, 3- 


39 




Dire 


ctory Label, 


2-21 




Dire 


ctory Label 


Data, 




2- 


33, 3-BO 






Erro 


r M^de, 3-64 






Logi 


n Vector, 3- 


38 




Seri 


al Number, 3 


-88 




Vers 


ion Number, 


3-17 




return 


address, 1- 


21 




Return 


and Di sp lay 


Error Mode, 


3- 


64 






return 


ed error cod 


es, 2-31 




RSX, 1 


-6, 1-11, 1- 


21, 1-23, 





1-25, 3-74, 4-20 
active, 1-9 
attach, 1-9 



file fo) 



1-25 



flags, 1-25 

header, 1-9, 1-21, 1-24, 

nonbanked flag, 1-25 

prefix, 4-21 

programs, 4-20 

remove flag, 1-25 
RSX Parameter Block, 3-74 
rub/del, 3-13 



Search a«a Delete, 2-16 

search chain, 1-20 

Search For First, 3-24 

Search For Next, 3-24, 3-26 

sectors, 3-65 

Select Disk, 2-29, 2-33, 3-19 

sequential file, 2-12 

sequential l/O processing, 2-26 

serial device l/O, 2-2 

serial number, 3-88 

Set 

BDOS Error Mode, 3-64 

Console Mode, 3-91 

Date and Time, 3-85 

Default Password, 2-23, 3-87 

Directory Label, 1-25, 
2-21, 2-22, 3-78 

DMA Address, 3-40 

Error Mode, 2-29 

File Attributes, 2-16, 2-17, 
2-22, 2-28, 3-44 

file byte count, 2-17 

Wilti-Sector Count, 
2-26, 3-63 

Output Delimiter, 3-93 

Program Return Code, 3-89 

Random Record, 3-55 

User Code, 3-47 
SETDEF utility, 1-19, 

1-20, 1-27 
Set/Get User Code, 3-47 
SET parameter, 3-69 
SPCB, 2-23, 2-24, 3-79 
SID'" Symbol File, 2-11 
sign-on message, 1-14 

BDO S , 1-11 

common region, 1-5 



compute Fi le 


BDOS, 


LOADER, 


, 1-11 




record, 


, 2-7 




transit 


jnt program. 
Lies, 2-13 


space 
disk, : 


3^65 




sparse, : 
sparse fi 


2-12 
Lie, 2- 


-12 



n 
n 
r 



SPR, 2-11 

standard CP/M command lin 

1-17 
startiard delete, 3-27 
standard aearch, 3-24 
start scroll, 3-2 
stc?i scroll, 3-2 
aubfields, 2-24 
SUB filetype, 1-19 
submit 

command line, 1-26 

file, 1-15, 1-18, 
1-20, 1-26 
SUBMIT, 1-19 

RSX, 1-27 

utility, 1-13, 1-26 
successful function, 2-32 
SYM, 2-11 
SYS, 2-11 

SYS attribute, 1-18 
Sys. Page Seloc, 2-11 

attribute, 1-lS 
cold start, 1-11, 
1-12, 1-13 



1-7 



1-5 



1-14 



modules, 1-5 
caseation, 1-13 
pron^Jt, 1-13, 1-15, 
1-16, 1-28 

tracks,' 1-12, 1-14, 1-15 
warm start, 1-11, 1-12, 
1-15, 1-25 
System Control Block, 1-27, 

3-69, 3-70 
System File, 2-11 
System Reset, 3-1 



tab characters, 3-2 
tab expansion, 2-3, 2-5 
temporarily allocated dat, 
block, 3-75 

file. 2-11 

file drive, 1-27, 3-71 

submit file, 1-27 



Test and Write Record, 3-60 

TEX, 2-11 

TEX Formatter Source, 2-11 

TPA, 1-6, 1-15, 1-21, 1-22 

size, 1-11 

space, 1-21 
transient commands, 1-8 
transient program, 1-4 to 1-9, 
1-11 to 1-13 , 1-ia, 
1-22, 2-7 

area, 1-6, 1-7 

size, 1-11 
true status, 2-6 
Truncate File, 2-22, 3-76 
TYPE, 1-18 
types of file stamps, 2-24 

U 

Unlock Record, 3-62 
unsuccessful function, 2-32 
update 

date and time stamp, 
3-35, 3-50 

directory label, 3-78 

stanp types, 2-24 



cede, 



3-47 

d, 1-12 
rectories, 2-18 
mber, 1-12, 1-15, 1-18, 
1-20, 1-28, 2-18, 3-47 



3-71 

zero, 1-20, 2-17, 
USER, 1-18 
User 0, 2-18 



2-18 



2-19, 3-20 



VALUE parameter, 3-69 
vers ion -independent 

programming, 3-17 
version number, 3-70 
virtual file size, 3-53 



rm start, 1-11, 1-15, 

1-22, 1-25, 3-1 
Idcard characters, 1-13 
ite data record, 3-31 



n 
n 
n 

Sequential, 2-30, 3-31 fl 

ite-Dending records, 3-68 I 



Write 

Pile XFCB, 2-22, 3-83 
Protect Diak, 3-42, 3-43 
Random, 2-30, 3-50 
Random with Zero Pill, 
2-30, 3-59 






XFCB, 2-19 
delete, 3-27 
Write Pile, 2-22 



n 

p 
p 
p 
p 
p 



NOTES 



NOTES 



COPYRIGHT 

Copvriqlit © 1983 Digital Research Inc. All rights reserved. No 
Dart of this publication may he reproduced, transmitted. 



ibed, stored 



slated 



From time t 



ally included i 



me changes are nade in the filenames and in the file: 



disk. This manual should not 
entation or warranty that such files or 



iterials and programs distributed. Most distribution disks include 
"KEADME.DOC" file. This file explains variations from the manual 
Tich do constitute modification of the manual and the items 
Deluded therewith. Be sure to read this file before using the 



TRADEMARKS 

CP/m and Digital Research and it 

Diqital Research Inc. Cp/M Plus. 

XREF are trademarks of Digital Research Inc. Altos is a register. 

trademark of Altos Corporation. IBM is a registered trademark ( 

International Business Machines. Intel is a registered trademark i 

Intel Corporation. Microsoft is a registered trademark of Microso 

Corporation. Zilog and Z80 are registered trademarks of Zilog Ini 

The CP/M Plus (CP/M Version 3) Operating System Sy stem Guide wi 
prepared using the Digital Research TEX" Text Formatter and print, 
in the United States of America, 

• First Edition: January 1983 • 

* Second Edition: July 1983 * 



n 
n 

n 



language, in any form^ ojr^by any means^ | 



eiet^uL^..^^, .M=. .^--, magnetic, optical, chemical, manual or 

otherwise, without the prior written permission of Digital Research 
Inc., 60 Garden Court, Box DRI, Monterey, California 93942. 

DISCLAIMER ' ' 

DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH _ 

RESPECT TO THE CONTENTS HEREOF AKD SPECIFICALLY DISCLAIMS ANY 
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR ] I 

PURPOSE. Further, Digital Research Inc. reserves the right to 
revise this publication and to make changes from time to time in the 
content hereof without obligation of Digital Research Inc. to notify H | 

any person of such revision or changes. | \ 

NOTICE TO USER 



Foreword 

CP/M® 3, also marketed a« CP/« Pl„,™ 
°^'J';"'« ^°"if *"' '""i' "achines that u«e i 
pre/eo'eX'c°P/„?°;„, ■=;/" ' '= "P""0-"n,p.c.o.e .,« it. 

ff i.r^a ct.Va.'! ?V"" ""■^'' I""" Iheteatt e/cteJ ai CP/Mlj ji 
User s Guide ) describing the operating system utilities You shoni^ 
.1.0 be familiar ,itb the CP/M Plus jcP/H Version j, n" .r^?°" 
t llZ: a'A""?' " ?""' Ih ^e.fter cited as CP/M Plus Pro o?Im,?"! 

Seagg'i°g^^ ^i?iY;.° """'-'-' '^' ^cu-entl, t' &^l^elblin'g aSd 

moaulerot°"fhi roW' "'"»»>■ " »" overview o£ the component 
over-'ij'. o°l tr ,?„i"ti„\.'"'a-n'd-'dS J?r'u'c";res"„e'ci°s",a?//o°;^"e Z 
oont'a?n°s' ."^d.'? "f!;"; ""'" ' '"" =?""'<= hardware. Section 3 
StJuJJ^;,. ,^? f description of these functions and data 
dfS???h^j:; tollowed by instructions to assemble and link the 
distributed modules with your customized modules. Section I 

di = trtbutic'n~d °l",r""""'°" °' ""> ""Pl" <:^/« 3 BIOS on you 
oenerat, .nJ^ ^ l^ "' ' ?""°" 5 documents the procedure to 
dJEu5^",*.°e1,s5c°' '""' "'" ' ■^•'™- =•""" » '• • "»Pl« 

u.e o'r° 'J?V""'f =°""ln tables, and sample BIOS modules you can 
r- s?; 4Sif B^Tst'/s's^s a^^rc^^'rc*d.-nX-"pporT"t^^^^ 

f-St"" t^-c'p-M'^.syifi'e" '"' "'" ^- ''""''' o's-hrs-'thS 

code £"0^1:^,'%° K through H ar. listing, of the assembled source 
Sjn'^^ fl^t?i Je-r„^:r„'c-du"i"?o"re'wrn"ir.a°t'i„?-. -.Zll'JSU 

o"n^^;BY^k«\-pe^^-o-i^"V;Sl-•of--^^^^^^ 

S?n<, I ; "PP""''" I ""« the assembled source code tor the six 

SLdw ", r't '?" ^"""^ °" '"• '"=»•' '"""-IS Computer SyswJ 
hardware. It also contains a sample Submit til. to build a BIOS? 



Appendixes J and K ace tabular summaries af the public entry 
points and data items in the modules of the sample BIOS. Finally, 
Appendix L is a tabular summary of the thirty-three functions of the 
CP/M 3 BIOS, complete with entry parameters and returned values. 



Table of Contents 

CP/H 3 Operating System Overview 

1.1 Introduction to CP/M 3 

1.2 CP/M 3 System Components 

1.3 Communication Between Modules 

1.4 Banked and Nonbanked Systems 

1.5 Memory Requirements 

1.6 Disk Organization 

1.7 Hardware Supported 

1.7.1 Hardware Supported by CP/M 3 Banked System 

1.7.2 Hardware Supported by CP/M 3 Nonbanked System 

1.8 Customizing CP/M 3 

1.9 Initial Load (Cold Soot) of CP/M 3 

CP^ 3 BIOS Overview 

2.1 Organization of the BIOS 

2.2 System Control Block 

2.3 System Initialization 

2.4 Character I/O 

2.5 Disk I/O 

2.6 Memory Selects and Moves 

2.7 Clock Support 

CP/H 3 BIOS Functional Specifications 

3.1 System Control Block 

3.2 Character I/O Data Structures 

3.3 BIOS Disk Data Structures 

3.3.1 Drive Table 

3.3.2 Disk Pacameter Header 



Table of Contents 
(continued) 



3.3.3 Disk Parameter Block 40 M 

3.3.4 Buffer Control Block 44 ' ' 

3.3.5 Data Structure Macro Definitions 46 

3.4 BIOS Subroutine Entry Points 49 p 

3.4.1 System Initialization Functions 51 

3.4.2 Character I/O Functions 54 

3.4.3 Disk I/O Functions 58 ^ 

3.4.4 Memory Select and Move Functions 64 i i 

3.4.5 Clock Support Function 67 ' ' 

3.5 Banking Considerations 67 

3.6 Assembling and Linking Your BIOS 69 , 

CP/H 3 Saaple BIOS ftodulea m 

4.1 Functional Summary of BIOS Modules 71 1 ■ 

4.2 Conventions Used in BIOS Modules 73 

4.3 Interactions of Modules 73 | | 

4.3.1 Initial Boot 73 

4.3.2 Character I/O Operation 74 ■« 

4.3.3 Disk I/O Operation 74 | [ 

4.4 Predefined Variables and Subroutines 75 

4.5 BOOT Module 77 T* 

4.6 Character I/O 78 

4.7 Disk I/O 81 p, 

4.7.1 Disk I/O Structure 81 I I 

4.7.2 Drive Table Module (DRVTBL) 81 

4.7.3 Extended Disk Parameter Headers (XDPHs) ... 82 

4.7.4 Subroutine Entry Points 83 p] 

4.7.5 Error Handling and Recovery 84 j | 

4.7.6 Multiple Sector I/O 85 

4.8 MOVE Module 85 _ 

4.9 Linking Modules into the BIOS 86 I 



Table of Contents 
(continued) 

Systea Generation 

5.1 GENCPM Utility 87 

5.2 Customizing the CPMLDR 98 

5.3 CPMLDR Utility 100 

5.4 Booting CP/M 3 101 

Debugging the BIOS 103 



Appendixes 



A Removable Media Considecations 107 

B Auto-density Support 109 

C Modifying a Cp/M 2 BIOS Ill 

CPM3.SYS File Format 115 

E Root Module of Relocatable BIOS for CP/M 3 117 

F System Control Block Definition for CP/M 3 BIOS 129 

G Equates for Mode Byte Fields: MODEBAUD.LIB 131 

H Macro Definitions for CP/M 3 BIOS Data Structures: CPM3.L 133 

1 ACS 8000-15 BIOS Modules 

1.1 Boot Loader Module for CP/M 3 137 

1.2 Character I/O Handler for 380 Chip-based System . . 140 

1.3 Drive Table 144 

1.4 zaO DMA Single-density Disk Handler 144 

1.5 Bank and Move Module for CP/M Linked BIOS 152 

1.6 I/O Port Addresses for 280 Chip-based System .... 153 

1.7 Sample Submit File for ASC 8000-15 System 155 

J Public Entry Points for CP/M 3 Sample BIOS Modules , . . 157 

K Public Data Items in CP/M 3 Sample BIOS Modules 159 

L CP/M 3 BIOS Function Summary 161 



Tables, Figures, and Listings 



l-l. CP/M 3 Operating System Memory Requirements. . , , 7 

2-1. CP/M 3 BIOS Jump Vector 16 

2-2. CP/M 3 BIOS Functions 17 

2-3. Initialization of Page Zero IB 

2-4. CP/M 3 Logical Device Characteriatice 19 

2-5. BDOS Calls to BIOS in Nonbanked/Banked Systems . . 21 

2-6. Multiple Sector I/O in Nonbanked/Banked Systems. . 22 

2-7, Reaaing Two Contiguous Sectors in Banked System. . 23 

3-1. System Control Block Fields 29 

3-2. Disk Parameter Header Fields 37 

3-3. Disk Parameter Block Fields 40 

3-4. BSH and BLM Values 42 

3-5. Maximum EXM Values 42 

3-6. BLS and Number of Directory Entries 43 

3-7. PSH and PHM Values 44 

3-B. Buffer Control Block Fields 45 

3-9. Functional Organization of BIOS Entry Points ... 49 

3-10. CP/M 3 BIOS Function Jump Table Summary 50 

3-11. I/O Redirection Bit Vectors in 3CB 54 

4-1. CP/M 3 BIOS Module Function Summary 72 

4-2. Public Symbols in CP/M 3 BIOS 75 

4-3. Global Variables in BIOSKRNL.ASM 76 

4-4, Public Utility Subroutines in BIOSKRNL.ASM .... 76 

4-5. Public Names in the BIOS Jump Vector 77 

4-6. BOOT Module Entry Points 78 

4-7. Mode Bits 79 

4-8. Baud Rates for Serial Devices 79 

4-9. Character Device Labels 80 

4-10. Fields of Each XDPH 33 

4-11. Subroutine Entry Points 84 

4-12. Move Module Entry Points 86 

5-1. Sample CP/M 3 System Track Organization 99 

C-1. CP/M 3 BIOS Functions Ill 

D-l. CPM3.SYS File Format 115 

D-2. Header Record Definition 115 

K-i. Public Data items 159 

L-1. BIOS Function Jump Table Summary 161 



Tables, Figures, and Listings 
(continued) 



1.1, General Memory Organization of CP/H 3 4 

1-2. Memory Organization for Banked CP/M 3 System ... 5 

1-3. Memory Organization with Bank 1 Enabled 6 

1-4. Memory Organization in Nonbanked CP/M 3 System . . 7 

1-5. Memory Organization in Banked CP/M 3 8 

1-6. Memory Ocqarization in Nonbanked CP/M 3 9 

1-7. CP/M 3 System Disk Organization 10 

2-1. CP/M 3 System Tracks 19 

3.1 Disk Data Structures in a Banked System 35 

3.2 Disk Parameter Header Format 36 

3-3. Disk Parameter Block Format 40 

3-4. ALO and ALl 43 

3-5. Buffer Control Block Format 44 

4-1. XDPH Format 82 

Listings 

3-1. SCB.ASM File 28 

3-2. Sample Character Device Table 33 

3-3. Equates for Mode Byte Bit Fields 34 

E-1. Root Module of Relocatable BIOS for CP/M 3 . . . . 117 

F-1. System Control Block Definition for CP/M 3 BIOS. . 129 

G-1. Equates for Mode Byte Fields: MODEBAOD.LIB. ... 131 

H-1. Macro Definitions 133 

I-l. Boot Loader Module for CP/M 3 137 

1-2. Character I/O Handler for Z80 Chip-based System. . 140 

1-3. Drive Table 1** 

1-4. Z80 DMA Single-density Disk Handler 144 

1-5. Bank and Move Module for CP/M 3 Linked BIOS. . . . 152 

1-6. I/O Port Addresses for Z80 Chip-baaed System . . . 153 

1-7. Sample Submit File for ACS 8000-15 System 155 

j-1. Public Entry Points 157 



Section 1 
CP/M 3 Operating System Overview 



■fck, j^ section is an overview of the CP/M 3 operating system, 
with a description of the sygtein components and how they relate to 
each other. The section includes a discussion of memory 
configurations and supported hardware. The last portion summarizes 
the creation of a customized version of the CP/M 3 Basic Input 
Output System (BIOS). 

1.1 Introduction to CP/« 3 

CP/« 3 provides an environment for program development and 
execution on computer systems that use the Intel 80BD, 8085, or zao 
microprocessor chip. CP/M 3 provides rapid access to data and 
programs through a file structure that supports dynamic allocation 
of space for sequential and random access files. 

CP/M 3 supports a maximum of sixteen logical floppy or hard 
disks with a storage capacity of up to 512 megabytes each. The 
maximum file size supported is 32 megabytes. You can configure the 
number of directory entries and block size to satisfy various user 
needs. 

CP/M 3 is supplied in two versions. One version supports 
nonbank-switched memory; the second version supports hardware with 
bank-switched memory capabilities. CP/M 3 supplies additional 
facilities foe the bank-switched system, including extended command 
line editing, password protection of files, and extended error 
messages. 

The nonbanJted system requires B.5 kilobytes of memory, plus 
space for your customized BIOS. It can execute in a minimum of 32 
kilobytes of memory. 

The bank-switched system requires a minimum of two memory banks 
with 11 kilobytes of memory in Bank and 1.5 kilobytes in common 
memory, plus space for your customized BIOS. The bank-switched 
system provides more user memory for application programs. 

CP/M 3 resides in the file CPM3.SYS, which is loaded into 
memory by a system loader during system initialization. The system 
loader resides on the first two tracks of the system disk. CPM3.sys 
contains the distributed BDOS and the customized BIOS. 

The CP/M 3 operating system is distributed on two single- 
denaity, single-sided, eight-inch floppy disks. Digital Research 
supplies a sample BIOS that is configured for an Altos 8000-15 
mlccocomputet system with bank-switched memory and two single- 
density, single-sided, eight-inch floppy disk drives. 



CP/M 3 Syst.n, Gold, 1.2 CP/M 3 System Component. m. 

1.2 CP/M 3 System Components 

The CP/M 3 operating system consists of the following three j" 
modnlesi the Console Commana Processor (CCP) , the Basic Disk \\ 
operating System (BDOS) , and the Basic Input Output System (BIOS) . 

The CCP is a program that provides the basic user interface to p 
the facilities of the operating system. The CCP supplies six built- | , 
in commands: Sm, DOS, ERASE, BEBAMj;, TYPE, and USES. The CCP 
executes in the Transient Program Area (TPA) , the region of memory 
.here all application programs execute. The CCP contains the _^ 
Program Loader Module, which loads transient (applications) programs , ^ 
from disk into the TPA for execution. 

Th. BDOS is the logical nucleus and tils system of CP/M 3. The 
BDOS provides th. interface between the application program and the - 
physical input/output routines of the BIOS. 

The BIOS is a hardware-dependent module that interfaces the 
vironment. The BIOS performs ?" 
of a number 
lific hatdwari 
the target computer system. 

The BDOS and the BIOS modules cooperate to provide the CCP and 
other transient program, with batdware-independent acoess to CP/M 3 
facilities. Because the BIOS is configured tor different hardware 
environment, and the BDOS remain, constant, you can transfer 
programs that run under CP/M 3 unchanged to systems with different 
hardware configurations. 

1.3 Communication Betireen Module. 

The BIOS loads the CCP into the TPA at system cold and warm 
start. The CCP moves the Program Loader Module to the top of the 
TPA and uses the Program Loader Module to load transient programs. 

The BDOS contains a set of functions that th, CCP and 
applications programs call to perform disk and character input and 
output operations. 

The BIOS contains a Jump Table with a set of 33 entry points 
that the BDOS calls to Perform bs'aware-d.pendent primitive 
Eunctiona, such as peripheral device I/O. For 
entry point o£ the BIOS called by the BDOS to r 
input character. 



BDOS to a particular hardware environment. The BIOS [ 
Dhysioal I/O in the system. The BIOS consists of 
Routines that you must configure to support the specific 



CP/M 3 Systein Guide 1.3 Communication Between Modules 

Similarities exist between the BDOS functions and the BIOS 
functions, particularly for simple device I/O. For example, when a 
transient program makes a console output function call to the BDOS, 
the BOOS makes a console output call to the BIOS. In the case of 
disk I/O, however, this relationship is more complex. The BDOS 
might make many BIOS function calls to perform a single BDOS file 
I/O function. BDOS disk l/o is in terms of 128-byte logical 
records. BIOS disk l/o is in terms of physical sectors and tracks. 

The System Control Block (SCB) is a 100-byte, decimal, CP/M 3 
data structure that resides in the BDOS system component. The BDOS 
and the BIOS communicate through fields in the SCB. The SCB 
contains BDOS flags and data, CCP flags and data, and other system 
information, such as console characteristics and the current date 
and time. You can access some of the System Control Block fields 
from the BIOS. 

Note that the SCB contains critical system parameters which 
reflect the current state of the operating system. If a program 
modifies these parameters, the operating system can crash. See 
Section 3 of this manual, and the description of BDOS Function 49 in 
the CP/M Plus Programmer's Guide for more information on the System 
Control Block. 

Page Zero is a region of memory that acts as an interface 
between transient programs and the operating system. Page Zero 
contains critical system parameters, including the entry to the BDOS 
and the entry to the BIOS Warm BOOT routine. At system start-up, 
the BIOS initializes these two entry points in Page Zero. All 
linkage between transient programs and the BDOS is restricted to the 
indirect linkage through Page Zero. Figure 1-1 illustrates the 
general memory organization of CP/M 3. 



CP/M 3 System Guide 



1.3 Communication Between Modules p« 



BIOS: Basic I/O Syslen 



BDOS: Basic Disk Operating System 



PAGE ZERO 



Figure 1-1. General Henory Organization of CP/H 3 



Note that all memory regions in CP/M 3 are page aligned, which 
means that they must begin on a page boundary. Because a page is 
defined as 236 (lOOH} bytea, a page boundary always begins at a 
hexadecimal address where the low-order byte of the hex address is 



1.4 Banked and Nonbanked Syateas 

CP/M 3 is supplied in two versions: one for hardware that 
supports banked memory, and the other for hardware with a minimum of 
32 kilobytes of memory. The systems are called banked and 
nonbanked. 

Digital Research supplies System Page Relocatable (.SPR) files 
for both a banked BOOS and a nonbanked BDOS. A sample banked BIOS 
is supplied for you to use as an example when creating a customized 
BIOS for your set of hardware components. 



CP/M 3 System Guide 



1.4 Banked and Nonbankcd Systems 



janizatior for a banked 
e for the ope eating system, 
which contains the Page Zero 
al banks to enhance operating 



The following figure shows thi 
system. Bank and common memory i 
Bank 1 la the Transient Prograni Area 
region of memory. You can use additic 
system performance. 

In banked CP/M 3 systems, CPMLDR, the system loader, loads part 
of the BDOS into common memory and part of the BDOS into Bank 0. 
CPMLDR loads the BIOS in the same manner. 

organization for the banked version 



Top ol Banked 




Hafdware-Dependenl Butter Space 
Resident Operating System Modules 




Figure 1-2. Heaory Organisation for Banked CP/H 3 System 



In this figure, the top region of memory is called 
memory. Common memory is always enabled and addressable. The 
operating system is divided into two modules: the resident portion, 
which resides in common memory, and the banked portion, which 
resides just below common memory in Bank 0. 

The shaded areas in Figure 1-2 represent the memory available 
to transient programs. The clear areas are used by the operating 
system for disk [ - ■ -- - -■ -■ 



CP/M 3 System Guide 



1.4 Banked and Nonbanked Systems 



space that can be allocated for data buffets by GENCPM, the CP/M 3 
system generation utility. The minimum size of the buffer area is 
determined by the specific hardware requirements of the host 
microcomputer system. 

Bank 0, the system bank, is the bank that ia enabled when CP/M 
3 is cold started. Bank 1 is the transient program bank. 

The transient program bank must be contiguous from location 
zero to the top of banked memory. Common memory must also be 
contiguous. The other banks need not begin at location zero or have 
contiguous memory. 



Top of memofy 




Dependeni Buffer Space 
Operating System Modules 



Figure 1-3. Henory Organization witb Bank 1 Enabled 
in Banked System 



The operating system switches to Bank i 
pec forming operating system functions. In 
switching performed by the operating system is 
calling program. 



other banks when 
jeneral , any bank 
;Eansparent to the 



much simpler, 



CP/M 3 System Guide 



1.4 Banket^ and Honbanked Systems 




Figure 1-4, Heoory Ocganization in Nonbanked CP/H 3 Systea 



In the nonbanked version of CP/M 3, memory consists of a single 
contiguous region addressable from OOOOH up to a maximum of OFPPFH, 
or 6 4K-1. The clear area above the operating system represents 
space that can be allocated for data buffers and directory hash 
tables by the CP/M 3 system generation utility, GENCPM, or directly 
allocated by the BIOS. The minimum size of the buffer area is 
determined by the specific hardware requirements of the host 
microcomputer system. Again, the shaded region represents the space 
available for transient programs. 



1.5 HeBocy RequireHents 



of the CP/H 3 oper; 



Table 1-1. CP/M 3 Operating Systea 


HeBory Requi 


regents 


CP/M 3 Version 


Nonbanked 


Banked 
Common Bank 


BDOS 6 . 5K 

BIOS (values vary) 

floppy system 1.5K 

hard system 2.5K 


1.5K 

.75K 
1.5K 


IIK 

2K 
3K 



The CP/M 3 banked system requires a minim 
and Bank 1) and can support up to 16 banks of 
n region is often 16K, but can be as 
ist be large enough to contain the reqL.ii-=" 

I of the operating system, which 



(common) por 



of two banks (Bank 
imory. The size of 
all as 4K. Common 
red buffers and the 



1.5K BDOS and the common part of your customized BIOS. 



CP/M 3 System Guide 



1,5 Memocy Requirements 



In a banked environment, CP/M 3 ma 
buffers and directory records using 
buffering scheme. The LRU buffer is thi 
system runs out of buffer spai 



intains a cache of deblocking 
a Least Recently Used (LRU) 
i first to be reused when the 
separate buffet 



pools for directory and data record caching. 

The RSX modules shown in Figure 1-5 are Resident System 
Extensions (RSX) that ate loaded directly below the operating system 
when included in an application ot utility progtan. The Program 
Loader places the RSX in memory and chains BDOS calls through the 
RSX entry point in the RSX. 



nizatii 



typical bank- 



COMMON MEMORY 



BANKED BIOS 3K 



LRU DATA BUFFERS 
RESIDENT BIOS 1« 



RESIDENT BDOS 1 .5K 



PROGRAM LOADER 



Stacked RSX Moi 



LRU DATA SUFFERS 



COPY OF CCP FOR 

WARM START 

(oplionalj 



TRANSIENT PROGRAM 



BANK BANK 1 BANK 2 

Figure 1-5. Henory Organisation in Banked CP/H 3 



CP/M 3 System Guide 



1.5 Memory Requirements 



The banked system supports a TPA of 6aK or more. The banked 
portion o£ the operating system in Bank requires at least 16K of 

memory. 

In the banked system, the BD05 and the BIOS are separated into 
two parts: a resident portion, and a banked portion. The resident 
BDOS and BIOS are located in common memory. The banked BDOS and 
BIOS are located in the operating system bank, referred to as Bank 
in this manual. 

The TPA extends from lOOH in Bank 1 up to the bottom of the 
resident BDOS in common memory. The banked BIOS and BDOS reside in 
Bank with the directory buffers. Typically, all data buffers 
reside in common. Data buffers can reside in an alternate bank if 
the system has a DMA controller capable of transferring arbitrary 
blocks of data from one bank to another. Hashed directory tables 
(one per drive) can be placed in any bank except Bank 1 (TPA) . 
Hashed directory tables require 4 bytes per directory entry. 

Figure 1-6 shows a typical nonbanked system configuration. 



PROGRAM LOADER 



TRANSIENT PROGRAM 
BASE PAGEOh-IOOn 



Figure 1-6. Heaory Organization in Honbanked CP/M 3 



The nonbanked CP/M 3 system requires 8.5K of memory plus space 
for the BIOS, buffers, and hash tables, allowing a TPA size of up to 
52K to 54K, depending on the size of the BIOS and the number of hash 
tables and buffers you are using. 



CP/M 3 System Guide 



1.6 Disk Organizatii 



1.6 Disk Ocganixatlon 

Figure 1-7 illustrates the organization of a CP/M 3 system 



CP/M 3 Dala Regioi 



CP/M 3 Direclory Regio 



CCP (Oplional) 



Figure 1-7. CP/M 3 Systen Disk Organisation 



In Figure 1-7, the first N tracks are the system tracks; the 
remaining tracks, the data tracks, are used by CP/H 3 for file 
storage. Note that the system tracks are used by CP/M 3 only during 
system cold start and warm start. All other CP/M 3 disk access is 
directed to the data tracks of the disk. To maintain compatibility 
with Digital Research products, you should use an eight-inch, 
single-density, IBM* 3740 formatted disk with two system tracks. 



1.7 Hardware Supported 

You can customize the BIOS to match any hardware environment 
with the following general characteristics. 



CP/M 3 System Guide 1.7 Hardware Supported 

1.7.1 Hacdware Supported by CP/H 3 Banked Systea 

• Intel 8080, Intel 8085, or Zilog Z80 CPU or equivalent. 

• A ininimuiB of two and up to sixteen banks of memory with the top 
4K-32K in common memory. Bank 1 must have contiguous memory 
£rom address ODOOH to the base of common memory. A reasonable 
configuration consists o£ two banks of 48K RAM each, with the 
top 16K in common memory, 

• One to sixteen disk drives of up to 512 megabytes capacity 
each. 

• Some form of ASCII console device, usually a CRT. 



1.7.2 Hardwace Supported by CP/H 3 Nonbanked Systea 

• Intel 8080, Intel 8085, or Zilog Z80 CPU or equii 



• Some form of ASCII console device, usually a CRT. 

al input and or output devices, usually 



Because most CP/M-compatible software is distributed on eight- 
inch, soft-sectored, single-density floppy disks, it is recommended 
that a CP/M 3 hacdware configuration include a minimum of two disk 
drives, at least one of which is a single-density floppy disk drive. 

1.8 CuBtonizing CP/M 3 

Digital Research supplies the BQ05 files for a banked and a 
nonbanked version of CP/M 3. A system generation utility, GenCPM, 
is provided with CP/M 3 to create a version of the operating system 
tailored to your hardware. GENCPM combines the BDOS and your 
customized BIOS files to create a CPM3.SYS file, which is loaded 
into memory at system start-up. The CPM3.SYS file contains the BDOS 
and BIOS system components and information indicating where these 
modules reside in memory. 



CP/M 3 System Guide l.B Customizing CP/M 3 

Digital Research supplies a CP/M 3 loader file, CPMLDR, which 
you can link with your customized loader BIOS and use to load the 
CPM3.SYS file into memory. CPMLDR is a small, self-contained 
version of CP/M 3 that supports only console output and sequential 
file input. Consistent with CP/M 3 organization, it contains two 
modules: an invariant CPMLDR_BDOS, and a variant CPMLDR_BIOS, which 
is adapted to match the host microcomputer hardware environment. 
The CPMLDR_B10S module can perform cold start initialization of I/O 
ports and similar functions. CPMLDR can display a memory map of the 
CP/M 3 system at start-up. This is a GENCPH option. 

The following steps tell you how to create a new version of 
CP/H 3 tailored to your specific hardware. 



isemble 


a cj 


stomi 


zed 


BIOS t 


:oll< 


Dwing 


the 


IS descr 


ibed 


in 


S> 


ictio 


.n 3. 


This software 


: cor r espond 


to ttl 




ct 


physi 


cal 


s of the 


targ 




system. 


includ 


ing 




and 


sses , 


per: 


Lpher 


al 


types, 




Id dr 


ive 



2) Use the system genecationi utility, GENCPM, to create the 
CPM3.SYS file containing the CP/M 3 distributed BDOS and 
your customized BIOS, as described in Section 5. 

3) Write a customized loader BIOS (LDRBIOS) to reside on the 
system tracks as part of CPMLDR. CPMLDR loads the CPH3.SYS 
file into memory from disk. Section 5 gives the 
instructions for customizing the LDRBIOS and generating 
CPMLDR. Link your customized LDRBIOS file with the 
supplied CPMLDR file. 

r system tracks 

5) Test and debug your customized version of CP/M 3. 

If you have banked memory, Digital Research recommends that you 
first use your customized BIOS to create a nonbanked version of the 
CP/H 3 operating system. You can leave your entire BIOS in common 
memory until you have a working system. Test all your routines in a 
nonbanked version of CP/M 3 before you create a banked version. 

1.9 Initial Load (Cold Boot) of CP/H 3 

into memory as follows. Execution is 
e procedure. The first stage consists of 
all program, called the Cold Boot Loader, 
if the Boot disk. This load operation ia 
hardware feature associated with system 
reset. The Cold Boot''Loader is usually 128 or 256 bytes in length. 





CP/M 


3 


is Ic 


lad. 


Init 


iated 


by 


a four 


-3t 


load 


ing into 


memory 




from 


the syst 


tem trc 


ICk! 


typi 


cally 


ha 


ndled 


by 



CP/M 3 System Guide 1,9 Initial Load (Cold Boot) of CP/M 3 

In the second stage, the Cold Boot Loader loads the memory 
image of the CP/M 3 system loader program, CPMLDR, from the system 
tracks of a disk into memory and passes control to it. For a banked 
system, the Cold Boot Loader loads CPMLDB into Bank 0. A PROM 
loader can perform stages one and two. 

In the third stage, CPMLDR reads the CPMB.SYS file, which 
contains the BDOS and customized BIOS, from the the data area of the 
disk into the memory addresses assigned by GBSCPM. In a banked 
system, CPMLDR reads the common part of the BDOS and BIOS into the 
common part of memory, and reads the banked part of the BDOS and 
BIOS into the area of memory below common_base in Bank 0. CPMLDR 
then transfers control to the Cold BOOT system initialization 
routine in the BIOS. 

For the final stage, the BIOS Cold BOOT routine, BIOS Function 
0, performs any remaining necessary hardware initialization, 
displays the sign-on message, and reads the CCP from the system 
tracks or from a CCP.COM file on disk into location lOOH of the TPA. 
The Cold BOOT routine transfers control to the CCP, which then 
displays the system prompt. 

Section 2 provides an overview of the organization of the 
System Control Block and the data structures and functions in the 
CP/M 3 BIOS. 

End of Section 1 



Section 2 

CP/M 3 BIOS Overview 



This section describes the organization of the CP/M 3 BIOS and 
the BIOS jump vector. It provides an overview of the System Control 
Block, followed by a discussion of system initialization procedures, 
character I/O, clock support, disk I/O, and memory selects and 



2.1 Organization of the BIOS 

The BIOS is the CP/M 3 module that contains all hardware- 
dependent input and output routines. To configure CP/M 3 for a 
particular hardware environment, use the sample BIOS supplied with 
this document and adapt it to the specific hardware of the target 
system. 

Alternatively, you can modify an existing CP/M 2.2 BIOS to 
install CP/M 3 on your target machine. Note that an unmodified CP/M 

2.2 BIOS does not work with the CP/M 3 operating system. See 
Appendix C for a description of the modifications necessary to 
convert a CP/M 2.2 BIOS to a CP/M 3 BIOS. 

The BIOS is a set of routines that performs system 
initialization, character-oriented I/O to the console and printer 
devices, and physical sector I/O to the disk devices. The BIOS also 
contains routines that manage block moves and memory selects for 
systems with bank-switched memory. The BIOS supplies tables that 
define the layout of the disk devices and allocate buffer space 
which the BDOS uses to perform record blocking and deblocking. The 
BIOS can maintain the system time and date in the System Control 
Block, 

Table 2-1 describes the entry points into the BIOS from the 
Cold Start Loader and the BDOS. Entry to the BIOS is through a jump 
vector. The jump vector is a set of 33 jump instructions that pass 
program control to the individual BIOS subroutines. 

You must include all of the entry points in the BIOS jump 
vector in your BIOS, However, if your system does not support some 
of the functions provided for in the BIOS, you can use empty 
subroutines for those functions. For example, if your system does 
not support a printer, JMP LIST can reference a subroutine 
consisting of only a RET instruction. Table 2-1 shows the elements 
of the jump vector. 



CP/M 3 System Guide 



2.1 Organizattt 



of the BIOS 







Table 


2-1. CP/H 3 BIOS JuHp Vector 


No. 


Ins 


truction 


Description 





JHP 


BOOT 


Perform cold start initialization 


1 


JMP 


WBOOT 


Perform warm start initialization 


2 


JMP 


CONST 


Check for console input character ready 


3 


JMP 


CON IN 


Read Console Character in 


4 


JMP 


COSOUT 


Write Console Character out 


5 


JMP 


LIST 


Write List Character out 


6 


JMP 


AUXOOT 


Write Auxiliary Output Character 


7 


JMP 


AUXIN 


Read Auxiliary Input Character 


B 


JMP 


HOME 


Move to Track 00 on Selected Disk 


9 


JMP 


SELDSK 


Select Disk Drive 


10 


JMP 


SETTRK 


Set Track Number 


11 


JMP 


SETSEC 


Set Sector Number 


12 


JMP 


SETDMA 


Set DMA Address 


13 


JMP 


READ 


Read Specified Sector 


14 


JMP 


WRITE 


Write Specified Sector 


15 


JMP 


LISTST 


Return List Status 


16 


JMP 


SECTRN 


Translate Logical to Physical Sector 


17 


JMP 


CONOST 


Return Output Status of Console 


18 


JMP 


AOXIST 


Return Input Status of Aux. Port 


19 


JMP 


AUXOST 


Return Output Status of Aux. Port 


20 


JMP 


DEVTBL 


Return Address of Char. I/O Table 


21 


JMP 


DEVINI 


Initialize Char. I/O Devices 


22 


JMP 


DRVTBL 


Return Address of Disk Drive Table 


23 


JMP 


MULTIO 


Set Number of Logically Consecutive 
sectors to be read or written 


24 


JMP 


FLUSH 


Force Physical Buffer Flushing for 
user-supported deblocking 


25 


JMP 


MOVE 


Memory to Memory Move 


26 


JMP 


TIME 


Time Set/Get signal 


27 


JHP 


5ELMEM 


Select Bank of Memory 


28 


JMP 


SETBNK 


Specify Bank for DMA Operation 


29 


JMP 


XMOVE 


Set Hank When a Buffer is in a Bank 
other than or 1 


30 


JMP 


USERF 


Reserved for System Implementot 


31 


JMP 


RESER71 


Reserved for Future Use 


32 


JMP 


RESERV2 


Reserved for Future Use 



Each jump address in Table 2-1 corresponds to a particular 
subroutine that performs a specific system operation. Note that two 
entry points are reserved for future versions of CP/M, and one entry 
point is provided for OEM subroutines, accessed only by direct BIOS 
calls using BDOS Function 50. Table 2-2 shows the five categories 
of system operations and the function calls that accomplish these 



CP/M 3 System Guide 2.1 Organization of the BIOS 

Table 2-2. CP/H 3 BIOS Functions 



Operation 


Function 


System Initial 


ization 

BOOT, WBOOT, DEVTBL, DEVINI, DRVTBL 


Character I/O 


CONST, CONIN, CONOUT, LIST, AOXOUT, AUXIN, 
LISTST, CONOST, AUXIST, ABXOST 


Disk I/O 


HOME, SELDSK, SETTRK, SETSBC, SETDMA , 
READ, WRITE, SECTRN , MULTIO , FLUSH 


Memory Selects 


and Moves 

MOVE, SELMEM, SETBNK, XMOVE 


Clock Support 


TIME 



You do not need to implement every function in the BIOS jump 
vector. However, to operate, the BOOS needs the BOOT, WBOOT, CONST, 

COKIN, CONOUT, HOME, SELDSK, SETTRK, SETSEC , SETDMA, READ, WHITE, 

SECTRK, MULTIO, and FLUSH subroutines. Implement SELMEM and SETBNK 
only in a banked environment. You can implement MULTIO, FLUSH, and 
TIME as returns with a zero in register A. DEVICE and some other 
utilities use the remaining entry points, but it is not necessary to 
Eully implement them in order to debug and develop the system. 



es but make the nonimplemented : 



>utin. 



2.2 System Control Block 

The System Control Block (SCB) is a data structure located in 
the BDOS. The SCB la a communications area referenced by the BDOS , 
the CCP, the BIOS, and other system components. The SCB contains 
system parameters and variables, some of which the BIOS can 
reference. The fields of the SCB are named, and definitions of 
these names are supplied as public variable and subroutine names in 
the SCB. ASM file contained on the distribution disk. See Section 
3,1 for a discussion oE the System Control Block. 



CP/M 3 System Guide 2.3 System Initialization 

2.3 SystcH Initialization 

When the BOOT and WBOOT routines of the BIOS get control, they 
must initialize two system parameters in Page Zero of memory, as 
shown in Table 3-3. 

Table 2-3. Initialization of Page Zeco 



0,1,2 Set to JMP WBOOT (OOOOH: JMP BIOS+3) . Location 
1 and 2 must contain the address of WBOOT in 
the jump vector. 

5,6,7 Set to JMP BDOS, the primary entry point to 
CP/M 3 for transient programs. The current 
address of the BDOS is maintained in the 
variable @MXTPA in the System Control Block. 
(See Section 3.1, "System Control Block," and 
BIOS Function 1: WBOOT on page 52.) 

The BOOT and WBOOT routine must load the CCP into the TPA in 
Bank 1 at location OlOOH. The CCP can be loaded in two ways. I£ 
there is sufficient space on the system tracks, the CCP can be 
stored on the system tracks and loaded from there. If you prefer, 
or if there is not sufficient space on the system tracks, the BIOS 
Cold BOOT routine can read the CCP into memory from the file CCP, COM 
on disk. 

If the CCP is in a .COM file, use the BOOT and WBOOT routines 
to perform any necessary system initialization, then use the BDOS 
functions to OPEN and READ the CCP.COM file into the TPA. In bank- 
switched systems, the CCP must be read into the TPA in Bank 1. 

In bank-switched systems, your Cold BOOT routine can place a 
copy of the CCP into a reserved area of an alternate bank after 
loading the CCP into the TPA in Bank 1. Then the Warm BOOT routine 
can copy the CCP into the TPA in Bank 1 from the alternate bank, 
rather than reloading the CCP from disk, thus avoiding all disk 
accesses during warm starts. 

There is a 128-byte buffer in the resident portion of the BDOS 
in a banked system that can be used by BOOT and WBOOT. The address 
of this buffer is stored in the SCB variable eBNKBF. BOOT and WBOOT 
can use this buffer when copying the CCP to and from the alternate 



ally partitioned as shown 



CP/M 3 System Guide 



2.3 System Initialization 



Goia 
StariLdr 


c™.o« 1 ,.-1,. 



Figuce 2-1. CP/M 3 Systea Tracks 



The cold start procedure is designed ao you need to initialize 
the system tracks only once. This is possible because the system 
tracks contain the system loader and need not change when you change 
the CP/M 3 operating system. The Cold Start Loader loads CPMLDR 
into a constant memory location that is chosen when the system is 
configured. However, CPMLDR loads the BDOS and BIOS system 
components into memory as specified in the CPH3.SYS file generated 
by GENCPM, the system generation utility. Thus, CP/M 3 allows the 
user to configure a new system with GENCPM and then run it without 
having to update the system tracks of the system disk. 

2.4 Character I/O 

CP/M 3 assumes that all simple character I/O operations are 
performed in 8-bit ASCII, upper- and lowercase, with no parity. An 
ASCII CRTL-Z (lAH) denotes an end-of-file condition for an input 



Table 


2-4. 


CP/M 3 Logical Device Characteristics 


Devic 




1 Characteristics 


CONIN, CONOUT 


The interactive console that 
communicates with the operator, 
accessed by CONST, CONIN, CONOUT, and 
CONOOTST. Typically, the CONSOLE is a 
device such as a CRT or teletype, 
interfaced serially, but it can also 
be a memory-mapped video display and 
keyboard. The console is an input 
device and an output device. 


LIST 




The system printer, if it exists on 
your system. LIST is usually a hard- 
copy device such as a printer or 
teletypewriter. 


AUXOOT 




The auxiliary character output device, 
such as a modem. 


AUXIN 




The auxiliary character input device, 
such as a modem. 



. Thi 


s means 


ar ftUXOUT, 


^o 


illows 




to 




lip^ 


nr.fi 


lide. 


The 
.t ur 


I/O 


ment i 


itil 



CP/M 3 System Guide 2.4 Character I/O 

Note that you can define a single peripheral as the LIST, 
AUXOOT, and AUXIN device simultaneously. If you assign no 
peripheral device as the LIST, AUXOUT, or AUXIN device, the AUXOUT 
and LIST routines can just return, and the AUXIN routine can return 
with a lAH (CTRL-Z) in register A to indicate an immediate end-of- 
f lie. 

CP/M 3 supports character device I/O redirection 
that you can direct a logical device, such as CONIN < 
one or more physical devices. The DEVICE utility ; 
reassign devices and display, and to change the cl 
configurations, as described in the CP/H Plus User' s Gi 
redirection facility is optional. You should not imple 
the rest of your BIOS is fully functional. 

2.5 Disk I/O 

The BOOS accomplishes disk I/O by making a sequence of calls to 
the various disk access subroutines in the BIOS. The subroutines 
set up the disk number to access, the track and sector on a 
particular disk, and the Direct Memory Access [DMA) address and bank 
involved in the I/O operation. After these parameters are 
established, the BOOS calls the READ or WRITE function to perform 
the actual I/O operation. 

Note that the BDOS can make a single call to SELDSK to select a 
disk drive, follow it with a number of read or write operations to 
the selected disk, and then select another drive for subsequent 
operations. 

CP/M 3 supports multiple sector read or write operations to 
optimize rotational latency on block disk transfers. You can 
implement the multiple sector I/O facility in the BIOS by using the 
multisector count passed to the MULTIO entry point. The BDOS calls 
MOLTIO to read or write up to 126 sectors. For every sector number 
1 to n, the BDOS calls SETDMA then calls READ or WRITE. 

Table 2-5 shows the sequence of BIOS calls that the BDOS makes 
to read or write a physical disk sector in a nonbanked and a banked 
system. Table 2-6 shows the sequence of calls the BDOS makes to the 
BIOS to read or write multiple contiguous physical sectors in a 
nonbanked and banked system. 



CP/M 3 System Guide 2.5 Disk I/O 

Table 2-5. BDOS Calls to BIOS in Honbanked and Banked Systeas 



Nonbanked BDOS 


Call 


Explanation 




SELDSK 


Called only when disk is 
selected or reselected. 


initially 


SETTRK 


Called for every 
physical sector. 


read or w 


ite of a 


SETSEC 


Called for every 
physical sector. 


read or w 


ite of a 


SETDHA 


Called for every 
physical sector. 


read or w 


ite of a 


READ, WRITE 


Called for every 
physical sector. 


read or w 


ite of a 


Banked BDOS 1 


SELDSK 


Called only when disk is 
selected or reselected. 


initially 


SETTRK 


Called foe every 
physical sector. 


read or w 


ite of a 


SETSEC 


Called for every 
physical sector. 


read or w 


ite of a 


SETDMA 


Called for every 
physical sector. 


read or w 


ite of a 


SETBNK 


Called for every 
physical sector. 


read or w 


ite of a 


READ, WRITE 


Called for every 
physical sector. 


read or w 


ite of a 



CP/M 3 System Guide 2.5 Disk I/O 

Table 2-6. Multiple Sector I/O in Monbanked and Banked SystsHs 

Nonbanked BDOS 



Called to inform the BIOS that the next r 
calls to disk READ or disk WRITE require s 
transfer of n contiguous physical sectors 



READ, WRITE 



Called for every read or write of 
physical sector. 



Called for every read 
physical sector. 



Banked BDOS 



Called to inform the BIOS that the ne> 
calls to disk READ or disk WRITE requi: 
transfer of n contiguous physical sect 
to contiguous memory. 



SETTRK 


Called for eve 




physical sector. 


SETSEC 


Called for eve 




physical sector. 


SETDMA 


Called for eve 




physical sector. 


SETBNK 


Called for eve 




physical sector. 


READ, WRITE 


Called for eve 




physical sector. 



CP/M 3 System Guide 



2.5 Disk I/O 



Table 2-7 shows the sequence of BDOS ca 
contiguous physical aectocs in a banked system. 



Table 2-7. Reading Two Contiguous Sectors in Banked Systea 



Call 


Explanatio 






SELDSK 


Called to initially 


select 


disk 


MULTIO 


With a value of 2 






SETTRK 


For first sector 






SETSBC 


For first sector 






SETDMA 


For first sector 






SETBNK 








R£AD 








SETTRK 


For second sector 






SETSEC 


For second sector 






SETDtlA 


For second sector 






SETBNK 








BEAD 









The CP/M 3 BDOS performs its own blocking and deblocking of 
logical 128-byte records. Unlike earlier versions of CP/M, the BIOS 
READ and WRITE routines always transfer physical sectors as 
specified in the Disk Parameter Block to or from the DMA buffer. 
The Disk Parameter Header defines one or more physical sector 
buffers which the BDOS uses for logical record blocking and 
deblocking . 



5 a cache of deblocking 
t Recently Used (LRU) 
; to be reused when the 
i separate buffer 



In a banked environment, CP/M 3 mainta 
buffers and directory records using a L* 
buffering scheme. The LRO buffer is the fi 
system runs out of buffer space. The BDOS maint 
pools for directory and data record caching. 

The BIOS contains the data structures to control the data and 
directory buffers and the hash tables. You can either assign these 
buffers and tables yourself in the BIOS, or allow the GENCPM utility 
to generate them automatically. 

Hash tables greatly speed directory searching. The BDOS can 
use hash tables to determine the location of directory entries and 
therefore reduce the number of disk accesses required to read a 
directory entry. The hash table allows the BDOS to directly access 
the sector of the directory containing the desired directory entry 
without having to read the directory sequentially. By eliminating a 
sequential read of the directory records, hashing also increases the 
percentage of time that the desired directory record is in a buffer, 
eliminating the need for any physical disk accesses in these cases. 
Hash tables and directory caches eliminate many of the directory 
accesses required when accessing large files. However, in a 
nonbanked system, hash tables increase the size of the operating 
system. 



CP/M 3 System Guide 2.5 Disk I/O 

When the BIOS finds an error condition, the READ and WRITE 
routines should perform several retries before reporting the error 
condition to the BOOS. Ten retries are typical. If the BIOS 
returns an error condition to the BDOS, the BDOS reports the error 
to the user in the following form: 

CP/M Error on d: Disk I/O 

The d: represents the drive specification of the relevant drive. 

To provide better diagnostic capabilities for the user, it is 
often desirable to print a more explicit error message from the BIOS 
READ or WRITE routines before the BIOS returns an error code to the 
BDOS. The BIOS should interrogate the SCB Error Mode Variable to 
determine if it Is appropriate to print a message on the console. 

2.6 HeMory Selects and Moves 

Four BIOS functions are provided to perform memory management. 
The functions are MOVE, XMOVE, SELMEM, and SETBNK. The XMOVE, 
SELMEM, and SETBNK memory management routines are applicable to the 
BIOS of banked systems. 

The BDOS uses the BIOS MOVE routine to perform memory- to- memory 
block transfers. In a banked system, the BDOS calls XMOVE to 
specify the source and destination banks to be used by the MOVE 
routine. If you use memory that is not In the common area for data 
record buffers, you must implement the XMOVE routine. 



The BDOS calls the SETBNK routine prior to calling disk READ or 
disk WRITE functions. The SETBNK routine must save its specified 
bank as the DMA bank. When the BDOS invokes a disk I/O routine, the 
I/O routine should save the current bank number and select the DMA 
bank prior to the disk READ or WRITE. After completion of the disk 
READ or WHITE, the disk I/O routine must reselect the current bank. 
Note that when the BDOS calls the disk I/O routines, Bank is in 
context (selected) . 

2.7 Clock Support 

If the system has a real-time clock or is capable oC keeping 
time, possibly by counting interrupts from a counter/timer chip, 
then the BIOS can maintain the time of day in the System Control 
Block and update the time on clock interrupts. BIOS Function 26 la 
provided for those systems where the clock is unable to generate an 



CP/M 3 System Guide 2.7 Clock Support 

The time of day is kept as four fields. gDATE is a binacy word 
containing the number of days since 31 December 1977. The bytes 
MOUR, §MIN, and esEC in the System Control Block contain the hour, 
minute, and second in Binary Coded Decimal (BCD) format. 

End of Section 2 



Section 3 
CP/M 3 BIOS Functional Specifications 



This section contains a detailed description of the CP/M 3 
BIOS. The section first discusses the BIOS data structures and 
their relationships, including the System Control Block, the drive 
table, the Disk Parameter Header, the Disk Parameter Block, the 
Buffer Control Blocks, and the character I/O table. The overview of 
the data structures is followed by a summary of the functions in the 
BIOS jump vector. A detailed description of the entry values and 
retdtned values for each jump instruction in the BIOS jump vector 
The last part of this section discusses the 
assembling and linking your customized BIOS. 

3-1 The Systea Control Block 

The System Control Block (SCB) is a data structure located in 
the BDOS. The SCB contains flags and data used by the CCP, the 
BDOS, the BIOS, and other system components. The BIOS can access 
specific data in the System Control Block through the public 
variables defined in the SCB. ASM file, which is supplied on the 
distribution disk. 

Declare the variable names you want to reference in the SCB as 
externals in your BIOS. ASM source file. Then link your BIOS with 
the SCB.REL module. 

the SCB. ASH file, the high-order byte of the various SCB 



addresses is defined as OFEH. The 



external 



EyuoLKs as page relocatable when generating a System Page 
Relocatable (SPR) format file. GENCPM recognizes page relocatable 
addresses of OFExxH as references to the System Control Block in the 
BDOS. GENCPM changes these addresses to point to the actual SCB in 
the BDOS when it is relocating the system. 

Do not perform assembly-time arithmetic on any references to 
the external labels of the SCB. The result of tne arithmetic could 
alter the page value to something other than OFEH. 

Listing 3-1 shows the SCB. ASM file. The listing shows the 
field names of the System Control Block. A @ before a name 
indicates that it is a data item. A ? preceding a name indicates 
that it is the label of an instruction. In the listing, r/w means 
Read-Write, and r/o means Read-Only. The BIOS can modify a Read- 
Write variable, but must not modify a Read-Only variable. Table 3-1 
describes each item in the System Control Block in detail 



CP/M 3 System Guide 



3.1 System Control Block 



title 



'Sys' 



1 Control Block Defii 



for CP/M3 BIOS' 



public ecivec, @covec, gaivec, gaovec, glovec, @bnkbf 
public eccdma, gcrdsk, @vinfo, gresel, efx, gustod 
public emltio, germde, gecdsk, @media, @bflgs 
public edate, ghour, gmin, esec, ?etjmp, @mxtpa 



scbSbase equ 

eCIVEC equ 

eCOVEC equ 

@AIVEC equ 

SAOVEC equ 

@LOVEC equ 

?BNKBP equ 

eCRDMA equ 

9CRDSK equ 

?VINFO equ 



euSRCD equ 

@MLTIO equ 

9ERMDE equ 

gERDSK equ 

9MEDIA equ 

@BPLGS equ 

gDATE equ 



9H0UR 
eMIN 
?SEC 
?ERJMP 



OFEOOH 

scbSbase 

scbSbase 

scbSbase 

scbSbase 

scbSbasE 

scbSbass 



i-22h 
i-24h 
^26h 
h28h 
i-2Ah 
t-35h 
scbSbase+3Ch 



scb$base+4Bh 
scbSbase+51h 
scbSbase+54h 

scbSba3e+57h 

scbSbaae+58h 

scbSbase+5Ah 
3cbSbase+5Bh 
scbSbase+5Ch 
scbSbase+5Fh 



Base of the SCB 

Console Input Redirect: 
Vector (word, r/w) 
Console Output Redirect 
Vector (word, t/w) 
Auxiliary Input r 



(w 



r/w) 



iliacy Output Redii 



(w 



r/w) 



List Output Redii 
Vector (word, r/w) 
Address of 128 Byte Buffer 
for Banked BIOS [word, r/o) 
Current DMA Address 
(word, r/o) 

Current Disk (byte, r/o) 
BDOS Variable "INFO" 
(word, r/o) 
FCB Flag (byte, r/o) 
BDOS Function for Error 
Messages (byte, r/o) 
Current User Code {byte, r/o) 
Current Multisector Count 
(byte, r/w) 

BDOS Error Mode (byte, r/o) 
BDOS Error Diak (byte, r/o) 
Set by BIOS to indicate 
open door (byte, r/w) 
BDOS Message Size Flag 
(byte, r/o) 
Date in Days Since 1 Jan 78 



[wort 
Hour 



r/w) 



r/w) 



BCD (byte. 
Minute in BCD (byte, r/w) 
Second in BCD (byte, r/w) 
BDOS Error Message Jump 
(3 bytes, r/w) 
Top of User TPA 
(address at 6,7) (word, r/o 



Listing 3-1. SCB. ASM File 



CP/M 3 System Guide 



3.1 System Control Block 



Table 3-1. System Control Block Fields 



eCIVEC, ecOVEC, @AIVEC, SAOVEC, eLOVEC [Read-Wcite 
Variable) 

These fieias ate the 16 bit I/O redirection 
vectors for the five logical devices: console 
input, console output, auxiliary input, 
auxiliary output, and the list device. (See 
Section 3.4.2, "Character I/O Functions.") 

eBNKBF (Read-only Variable) 

@BNKBF contains the address of a 128 byte 
buffer in the resident portion of the BDOS in a 
banked system. This buffer is available for 
use during BOOT and WBOOT only. You can use it 
to transfer a copy of the CCP from an image in 
an alternate bank if the system does not 
support interbank moves. 



§CRDMA, eFX, gUSRCD, gERDSK (Read-Only Variable) 

These variables contain the current DMA 
address, the BDOS function number, the current 
user code, and the disk code of the drive on 
which the last error occurred. They can be 
displayed when a BDOS error ia intercepted by 
the BIOS. See JERJMP. 



eCRDSK (Read-only Variable} 



nt default dr: 



gVlNFO, SRESEL (Read-Only Variable) 

If 9RESEL ia equal to OPPH then eviNFO contains 
the address of a valid FOB. If gRESEL is not 
equal to OFFH, then gVINFO Is undefined. You 
can use ^VINFC to display the f ilespec when the 
BIOS irttercepts a BDOS error. 



3.1 System Control Block 



Table 3-1. (continued) 



(Read-Write Variable) 



gMLTIO contai 
The BIOS ca 
directly, or 
value of the n 
to 128. 



Q current raultisector count, 
ange the multisector count 
>ugh BDOS Function 44. The 
sector count can range from 1 



SERMDE (Read-only Variable) 



displaying an 
the BDOS is 

d isplay ing 



the current BDOS error mode. 

the BDOS is returning error 
application program without 
;rror messages. OFEH indicates 
oth displaying and returning 
,er value indicates the BDOS is 
rors without notifying the 



PMEDIA [Read-Write Variable) 

SMBDIA is global system flag indicating that a 
drive door has been opened. The BIOS routine 
that detects the open drive door sets this flag 
to OFFH. The BIOS routine also sets the MEDIA 
byte in the Disk Parameter Header associated 
with the open-door drive to OFFH. 



eBFLGS (Read-only Variable) 



inds 



The BDOS in CP/« 3 produce 
messages: short error messages and extended 
error messages. Short error messages display 
one or two lines of text. Long error messages 
display a third line of text containing the 
filename, flletype, and BDOS Function Number 
involved in the error. 

In banked systems, GENCPM sets this flag in the 
System Control Block to indicate whether the 
BIOS displays short or extended error messages. 
Your error message handler should check this 
byte in the System Control Block. If the high- 
order bit, bit 7, is set to 0, the BDOS 
displays short error messages. If the high- 
order bit is set to 1, the BDOS displays the 
extended three-line error messages. 



3.1 System Control Block 



Table 3-1. 



(continued) 



For example, the BDOS diaplaya the following 
error message if the BIOS returns an error from 
READ and the BDOS is displaying long error 
messages. 



In the above error message. Function nn and 
filename. typ represent BDOS function number and 
file specification involved, respectively. 



@DATE (Read-Write Variable) 

The number of days since 31 December 1977, 
expressed as a 16-bit unsigned integer, low 
byte first, A real-time clock interrupt can 
update the @DATE field to indicate the current 



eaOUR, 8MIN, eSEC (Bead-Write Variable) 



These 2-digit B 
indicate the ci 
if updated by ; 



iry Coded Decimal (BCD) fields 
ent hour, minute, and second 
eal-time clock interrupt. 



7EBJMP (Read-Write Code Label) 

The BDOS calls the error message 
through this jump instruction, 
contains an error code as follows^ 



Permanent Error 
Read Only Disk 
Read Only File 
Select Error 
Password Error 
File Exists 
7 in Filename 



I the BDOS I 



CP/M 3 System Guide 



3.1 System Control Block 



Table 3-X. (continued) 



;ontinaed) 

The ?ERJMP vector allows the BIOS to intercept 
the BDOS error messages so you can display them 
in a foreign language. Note that this vector 
is not branched to if the application program 
is expecting return codes on physical errors. 
Refer to the CP/M Plus Programmer's Guide for 






?ERJMP is 



set to point to the default (English) 
sage routine contained in the BDOS. 



I modify the addr4 
to point to an alternate message 
Your error message handler can refer 
to gFX, eVINFO (if @RESEL is equal to OPFH) , 
gCRDMA, ecRDSK, and gOSRCD to print additional 
error information. Your error handler should 
return to the BDOS with a RET instruction after 
printing the appropriate message. 



ewXTPA (Head-Only Variable) 



gMXTPA contains the address of the current BDOS 
entry point. This is also the address of the 
top of the TPA. The BOOT and WBOOT routines of 
the BIOS must use this address to initialize 
the BDOS entry JMP instruction at location 
005H, during system initialization. Each time 
a RSX is loaded, @MXTPA is adjusted by the 
system to reflect the change in the available 
User Memory (TPA) . 



3.2 Character I/O Data Structures 



ce CHRTBL is a character table describing 

CHRTBL contains 6-byte physical device 

sties of each physical device. These 

mode byte, and the current baud rate, if 

DEVICE utility references the physical 

and attributes contained in your CHRTBL. 

DEVICE can also display the physical names and characteristics in 

your CHRTBL. 

The mode byte specifies whether the device is an input oc 
output device, whether it has a selectable baud rate, whether it is 
a serial device, and if XON/XOFF protocol is enabled. 



The BIOS data stru^ 
the physical I/O devic 
names and the charact 
characteristics includ. 
any, of the device, 
devices through th' 



— CP/M 3 System Guide 3.2 Character I/O Data Structures 

Listing 3-2 shows a sample character device table that the 
^ DEVICE Utility uses to set and display I/O direction. 



; sample character device table 

db 'CRT ' - console VDT 

db mbSinSout+mb5serial+mbSsoftSbaud 
db baud$9600 

db 'LPT ' ; system serial printer 

db mbSoutput+mbSsecial+mbSsoftSbaud+mbSxon 
db baudS9600 

db 'TISIO ' . alternate printer 

db mb5output+inb$seriaH-mbS9oft$baud 
db baudS9600 

db -MODEM ■ ; 300 baud modem pott 

db mbSinSout-t-mbSseriai+mbSsof t$baud 
db baudS300 

dt- 'VAX ■ . interface to VAX 11/780 

db mb$inSout4mb5serial-i-mbSsoet$baud 
db baud$9600 

db 'DIABLO- ; Diablo 630 daisy wheel pri 

db mbSoutput+mbSserial+mbS softs baud+rabSxonSxoEf 
db baud$1200 



db bauds 



CEN 

itput 



; Centronics type parallel printer 



Listing 3-2. Sample Character Device Table 



Listing 3-3 shows the equates for the fields contained : 
sample character device table. Many systems do not support ; 
these baud rates. 



ictet I/O Data Stri 



mbS input 
inb$output 
mbSin$oi]t 
mbSsoftSbaud 



mode byte fields 



device may do input 
device may do output 
tput r dev may do both 
software selectable 
, baud rates 
equ OOOOSlOOOb ; device may use protocol 
equ OOOlSOOOOb ; XON/XOFF protocol 
; enabled 



equ OOOOSOOOlb 
equ OOOOSOOlOb 
equ mb5input+mbSi 
equ 0000$0100b 



equates for baud rate byte 



bauds none 

baudSSO 

baudS75 

baudSllO 

baudS134 

baud$150 

baud$300 

baudSeOO 

baudS1200 

baudSlSOO 

baudS2400 

bauds 3600 

baudS4800 

baud$7200 

baud$9600 

baudS19200 



equ 1 
equ 2 
equ 3 
equ 4 

equ 12 



associated * 
50 baud 
75 baud 
110 baud 
134.5 baud 
150 baud 
300 baud 
600 baud 
1200 baud 
1800 baud 
2400 baud 
3600 baud 
4800 baud 
7200 baud 
, 9600 baud 
J 19.2k baud 



Listing 3-3. Equates for Mode Byte Bit Fields 



BIOS Disk Data Structures 

The BIOS includes tables that describe the particular 
ractecistios of the disk subsystem used with CP/M 3. This 
tion describes the elements of these tables. 

in general, each disk drive has an associated Disk Parameter 
der (DPH) that contains information about the disk drive and 
vides a scratchpad area for certain BDOS operations. One of the 
ments of this Disk Parameter Header is a pointer to the Disk 
ameter Block (DPB), which contains the actual disk description. 

In the banked system, only the Disk Parai 
common memory. The DPHs, checksum vector 
fer Control Blocks, and Directory Buffer; 
lory or Bank 0. The hash tables can resi. 
' bank except Bank 1. The data buffers 
lory if you implement the XMOVB function. 



ter Block m 
allocation 


ust reside 
vectors. 


can reside 


memory or 
in banked 



CP/M 3 System Guide 



3.3 BIOS Data Structures 



Figure 3-1 shows the relationships between the drive table, the 
Disk Parameter Header, and the Data and Directory Buffer Control 
Block fields and their respective data structures and buffers. 

Drive Table (adOtesses of DPHs) 



Checksum Vector 



■ DPB CSV ALV 



1 




1 ^"" 1 1 Link 1 
' 1 ' ' 1 ' 


L^ 


Directory Bjffar | 






acB 


1 1 ^"" 1 1 1 

L _ 1 , 1 1 ,_.! 


L^ 


Directory Buffer | 






BCB 


Ln" ir.l "Rh 


1 -1 


^\- 


Directory Buffer | ■= 



CE 



:u 



Figure 3-1. Disk Data Structures in a Banked System 



CP/M 3 System Guide 



3.3 BIOS Data Structures 



3.3.1 Drive Table 

The drive table consists of 16 words containing the addresses 
of the Disk Parameter Headers for each logical drive name, A through 

P, and takes the general form: 



drivetable dw dphO 
dw dphl 
dw dph2 



the corresponding 



lessee the drive table to locate the 
structures, so that it can determine 
to use, and optionally allocate the 
must supply a drive table if you want 
in. If certain addresses in the Disk 
Parameter Headers referenced by this drive table are set to OPPPEH, 
GENCPM allocates the appropriate data structures and updates the 
DPH. You can supply the drive table even if you have performed your 
own memory allocation. See the BIOS DRVTBL function described in 
Section 3.4.1. 



The GENCPM utility ac 
various disk parameter dati 
which system configuration 
various buffers itself. Yo 
GENCPM to do this allocat: 



3.3.2 Disk Paranetec Header 

In Figure 3-2, which shows the format of the Disk Parameter 
Header, b refers to bits. 



XLT 


-0- 


MF 


DPB 


CSV 


ALV 


DlflBCB 


DTABCB 


HASH 


HBANK. 


16b 


72b 


8b 


■t6b 


16b 


16b 


16b 


16b 


16b 


8b 



Figure 3-2. Disk P.;ra]ieter Header Format 



Table 3-2 des( 



ibes the fields of the Disk Pa 



I— CP/M 3 System Guide 



3.3 BIOS Data Structucea 



Table 3-2. Disk Pacaseter Header Fields 

Comments 

Set the XLT field to the address of the logical to 
physical sector translation table. If there is no 
sector translation and the logical and physical 
sector numbers are the same, set XLT to OOOOH. Disk 
drives with identical sector skew factors can share 
the same translation table. 



XLT : 



: the value passed to SECTRN in registers I 



Usually the translation table c< 


nsists of one byte 


per physical sector. Generally 


it is advisable to 


keep the number of physical s 


2ctors per logical 



translation table from becoming too large. In the 
case of disks with multiple heads, you can compute 
the head number from the track address rather than 
the sector address. 



These 72 bits (9 bytes) of zeroes ate the scratch 
area the BDOS uses to maintain various parameters 
associated with the drive. 



MP is the Media Flag. The BDOS resets MF to zero 
when the drive is logged in. The BIOS can set this 
flag and @MEDIA in the SCB to OFFH if it detects 
that a drive door has been opened. If the flag is 
set to OPFH, the BDOS checks for a media change 
prior to performing the next BDOS file operation on 
that drive. If the BDOS determines that the drive 
contains a new volume, the BDOS performs a login on 
that drive, and resets the MF flag to OOH. Note 
that the BDOS checks this flag only when a system 
call is made, and not during an operation. 
Usually, this flag is used only by systems that 
support door-open interrupts. 



Set the DPB field to the address of a Disk 
Parameter Block that describes the characteristics 
of the disk drive. Several Disk Parameter Headers 
can address the same Disk Parameter Block if their 
drive characteristics are identical, (The Disk 
Parameter Block Is described in Section 3.3.3.) 



CP/M 3 System Guide 



3.3 BIOS Data Structures 



Table 3-2. (continued) 



CSV 
detect 



. the address of a scratchpad . 



iqed disks. 



Thi 



addr 



used to 
must be 



Thet 



each 



leter 



ivery 



Dry). 



removable medii 
;t be one byte 

directory entries tor 12B bytes of dic^. j,. -- 

other words, lenqth(CSV) = (DRM/4)+l. (See Table 
3-3 for an explanation of the DBM field.) If the 
drive is permanently mounted, set the CKS variable 
in the DPB to 8000H and set CSV to OOOOH, This 
way, no storage is reserved for a checksum vector. 
The checksum vector may be located in common memory 
or in Bank 0. Set CSV to OPFFEH for GENCPM to set 
up the checksum vector. 



ALV is the address of the scratchpad 
the allocation vector, which the BDOS \ 
disk storage allocation information. 



area called 

ses to keep 

This area 






each dri 



vector usually requires 2 bits for 

the drive. Thus, length (ALV) = 

See Table 3-3 for an explanation of 

n the nonbanked version of CP/M 

lly specify that GENCPM reserve 

' allocation vector per block on 

length (ALV) - (DSM/e) + 



The allocat 

each block on ( 

(DSM/4) 4 2. (Sg 

the DSM field.) 

3, you can optioi 

only one bit in tue 

the drive. In thi: 

1. 

The GENCPM option to use single-bit allocation 

vectors is provided in the nonbanked version of 

CP/H 3 because additional memory is required by the 

double-bit allocation vector. This option applies 

to all drives on the system. 

With double-bit allocation vectors, CP/M 3 
:s, at every system warm start, 
lat are not permanently recorded 

^„ ^„^ „^ ^. Note that file space allocated 

to a file is not permanently recorded in a 
directory unless the file is closed. Therefore, 
the allocation vectors in memory can indicate that 
apace is allocated although directocy records 
indicate that space is free for allocation. With 
single-bit allocation vectors, CP/M 3 requires that 
a drive be reset before this space can be 
reclaimed. Because it increases performance, CP/M 
3 does not reset disks at system warm start. Thus, 
with single-bit allocation vectors, if you do not 
reset the disk system, DIR and SHOW can report an 
inaccurate amount of free space. With single-bit 



CF/M 3 System Guide 



3.3 BIOS Data Structures 



Table 3-2. (continued) 



ALV allocation vectors, the usee must type a CTRL-C at 

(continued) the system prompt to reset the disk system to ensure 

accurate reporting of free apace. Set ALV to 

OFFFEH for GENCPM to automatically assign space 

for the allocation vector, single- or double-bit. 



for the allocation vector, aj.iiyj.c- i^i. ijuuuj.c-uj.l, 
during system generation. In the nonbanked system, 
GENCPM prompts for the type of allocatii 
In the banked system, the allocation 
always double-bit and can reside in comi 
or Bank 0. When GENCPM automatically assigns space 
for the allocation vector (ALV = OFFFEH) , it places 
the allocation vector in Bank 0. 



DIRBCB Set DIRBCB to the address of 
Buffer Control Block (BCB) in 
Set DIRBCB to the address of a 
banked system. 



a single directory 
in unbanked system. 
BCB list head in a 



Set DIRBCB to OFFFEH for GENCPM to set up the 
DIRBCB field. The BOOS uses directory buffers for 
all accesses of the disk directory. Several DPHs 
can refer to the same directory BCB or BCB list 
head; or, each DPH can reference an independent BCB 
or BCB list head. Section 3.3.4 describes the 
format of the Buffer Control Block. 



DTABCB Set DTABCB to the address of a single data BCB in 
an unbanked system. Set DTABCB to the address of a 
data BCB list head in a banked system. 

Set DTABCB to OFFFEH for GENCPM to Set up the 
DTABCB field. The BDOS uses data buffers to hold 
physical sectors so that it can block and deblock 
logical 12B-byte records. If the physical record 
size of the media associated with a DPH is 12B 
bytes, you can set the DTABCB field of the DPH to 
OFFFPH, because in this case, the BDOS does not use 
a data buffer. 



EIASH contains the address ' 
hashing table associated 
OFFFFH to disable dlrecto 



f the option 


al directory 


*lth a DPH. 


Set HASH to 


y hashing. 





CP/M 3 System Guide 



3.3 BIOS Data ! 



Table 3-2. (continued) 



Comments 



Set HASH to OFFFEH to make directory hashing on the 
drive a GENCPM option. Each DPH using hashing must 
reference a unique hash table. IE a hash table is 
supplied, it must be 4* (DRM+1) bytes long, where 
DRM is one less than the length of the directory. 
In other words, the hash table must contain four 
bytes for each directory entry of the disk. 



Set HBANK to the bank number of the hash table, 
HBANK is not used in unbanked systems and should be 
set to zero. The hash tables can be contained in 
the system bank, common memory, or any alternate 
bank except Bank 1, because hash tables cannot be 
located in the Transient Program Area. GENCPM 
automatically sets HBANK when HASH is set to 
OFFFEH . 



3.3.3 Disk Paraaetec Block 



leter Block, where 



SPT 


BSH 


BLM 


EXM 


DSM 


DRM 


ALO 


AL1 


CKS 


OFF 


PSH 


PHM 


16D 


8b 


8b 


SO 


16b 


16b 


8b 


Bb 


16D 


16b 


Bb 


Bb 



Figure 3-3. Disk PBcaaeter Block FoEHst 



Table 3-3 describes the fields of the Disk Parameter Block. 
Table 3-3. Disk PacaBetar Block Fialds 



Field 


Comments 


SPT 


Set SPT to the total number of 128-byte logical 
records per track. 


BSH 


Data allocation block shift factor. The value 
of BSH is determined by the data block 
allocation size. 


BLM 


Block mask. The value of BLM is determined by 
the data block allocation size. 



CP/M 3 System Guide 



3.3 BIOS Data Structures 



(continued) 



Field 1 


Comments 


EXH 


Extent mask determined by the data block 
allocation size and the number of disk blocks. 


DSM 


Determines the total storage capacity of the 
disk drive. DSM is one less than the total 
number of blocks on the drive. 


DRH 


Total number of directory entries minus one that 
can be stored on this drive. The directory 
requires 32 bytes per entry. 


ALO, ALl 


Determine reserved directory blocks. See Figure 
3-4 for more information. 


CKS 


The size of the directory check vector, 
(DRM/4)+l. Set bit 15 of CKS to 1 if the drive 
is permanently mounted. Set CKS to 8000H to 
indicate that the drive is permanently mounted 
and directory checksumming is not required. 




Hote: full directory checksumming is required 
on removable media to support the automatic 
login feature of CP/H 3. 


OFF 


The number of reserved tracks at the beginning 
of the logical disk. OFF is the track on which 
the directory starts. 


FSH 


Specifies the physical record shift factor. 


PHM 


Specifies the physical record mask. 



CP/M allocates disk space in a unit called a block. Blocks are 
also called allocation units, or clusters. BLS is the number of 
bytes in a block. The block size can be 1024, 2048, 4096, 8192, or 
16384 (decimal) bytes. 

A large block size decreases the size of the allocation vectors 
but can result in wasted disk space, A smaller block size increases 
the size of the allocation vectors because there are more blocks on 



There is a restriction on the block size. If the block size is 
1024, there cannot be more than 255 blocks present on a logical 
drive. In other words, if the disk is larger than 256K, it Is 
necessary to use at least 2048 byte blocks. 



The 


value 


of 


BLS 


s 


rather, 


it is 


derived 


f 


Table 3- 


. 









CP/M 3 System Guide 3.3 BIOS Data Sti 

Table 3-4. BSH and BLH Values 



BLS 


BSH 


BLM 


1,024 


3 


7 


2,048 


4 


15 


4,096 


5 


31 


8,192 


6 


63 


16,384 


7 


127 



The value of the Block Shift Factor, eSH, is determined by the 
data block allocation size. The Block Shift Factor [BSH) equals the 
logarithm base two of the block size in 128-byte records, or 
LOG2(BLS/12B) , where L0G2 represents the binary logarithm function. 



Table 3-5. 


HaxUuB BXM 


Values 


s.. ! 


EXM va 


lues 




DSM<256 


DSM>255 


1,024 
2,048 
4,096 
8,192 
16,384 



1 
3 
7 
15 


N/A 


1 
3 
7 



less than the maximum number of 16K 



■ FCB. 



Set EXM to zero if you want media compatibility with an 
extended CP/H 1.4 system. This only applies to double-density CP/M 
1.4 systems, with disk sizes greater than 256K bytes. It is 
preferable to copy double-density 1.4 disks to single-density, then 
reformat them and recreate them with the CP/M 3 system, because CP/M 
3 uses directory entries more effectively than CP/M 1.4. 

DSM is one less than the total number of blocks on the drive. 
DSM must be less than or equal to 7FFFH. If the disk uses 1024 byte 
blocks (BSH-3, BLM=7), DSM must be less than or equal to OOFFH. The 
product BLS*(DSM+1) is the total number of bytes the drive holds and 
must be within the capacity of Che physical disk. It does not 
include the reserved operating system tracks. 



CP/M 3 System Guide 



The DRM entry Is one less than the total number of 32-byte 
directory entries, and is a 16-bit value. DRM must be less than or 
equal to (BLS/32 * 16) - 1. DRM determines the values of ALO and 
ALL The two fields ALO and ALl can together be considered a string 
of 16 bits, as shown in Figure 3-4. 



00 01 02 03 04 05 06 



09 10 n 12 13 



Figure 3-4. ALO and ALl 



Position 00 corresponds to the high-ori 
labeled ALO, and position 15 corresponds to the 
byte labeled ALl. Each bit position reserve: 
number of directory entries, thus allowing a 
sslgned for 



starting 
ALl overlay the fi 
associated drive, 
block sizes. 



illed to the right unt 

rst two bytes of the a 

Table 3-6 shows DRM i 



er bit of the byte 
low-order bit of the 
a data block for a 
maximum of 16 data 
issigned 



ximums for the < 



Table 3-6 


BItS and NuMber of Dicectory BntEies 


BLS 


Directory Entries 


Maximum DRM 


1,024 
2,048 
4,096 
8,192 
16,384 


32 • reserved blocks 
64 * reserved blocks 
lae * reserved blocks 
25G * reserved blocks 
512 * reserved blocks 


511 
1,023 
2,047 
4,095 
8,191 



If DRM = 127 (128 directory entries) , and BLS = 1024, there aj 
32 directory entries per block, requic ing 4 reserved blocks. 1 
this case, the 4 high-order bits of ALO are set, resulting in t) 
values ALO = OFOH and ALl = OOH. The maximum directory allocatit 
is 16 blocks where the block size is determined by BSH and BLM. 



The OFF field detei 
at the beginning of t 
mechanism for skipping 
system disks contain the 



mines the number of tracks that are skipped 
he physical disk. It can be used as a 
reserved operating system tracks, which on 
Cold Boot Loader, CPMLDR, and possibly the 
to partition a large disk into smaller 



CP/M 3 System Guide 



3.3 BIOS Data St: 



PSH and PHM determine the physical sector size of the disk. 
All disk I/O is in terms of the physical sector size. Set PSH and 
PS« to zero if the BIOS Is blocking and deblocking instead o£ the 
BDOS. 

PSH specifies the physical record shift factor, ranging from 
to 5, corresponding to physical record sizes of 128, 256, 512, IK, 
2K, or 4K bytes. It is equal to the logarithm base two of the 
physical record size divided by 128, or L0G2 [sector_size/128) . See 
Table 3-7 for PSH values. 

PHM specifies the physical cecocd mask, ranging from to 31, 
corresponding to physical record sizes of 128, 256, 512, IK, 2K, or 
4K bytes. It is equal to one less than the sector size divided by 
128, or, (sector_size/12B)-l. See Table 3-7 for PHM values. 



Table 3-7. 


PSH and PHH Values 


Sector 






size 


PSH 


PHM 


128 





256 


1 1 


512 


2 3 


1,024 


3 7 


2,048 


4 15 


4,096 


5 31 



3.3.4 Buffer Control Block 



Control Block (BCB) locates physical record buffers 
The BDOS uses the BCB to manage the physical record 
More than one Disk Parameter Header can 
GENCPM utility can create the Buffer 



A Buffe 
for the BDOS, 
buffers during proces 
specify the same BCB 
Control Block. 

Note that the BANK and LINK fields of the Buffer Control Block 
are present only in the banked system. Therefore, the Buffet 
Control Block is twelve bytes long in the nonbanked system, and 
fifteen bytes long in the banked system. Note also that only the 
DRV, BUFPAD, BANK, and LINK fields need to contain initial values. 
In Figure 3-5, which shows the form of the Buffer Control Block, b 
refers to bits. 



DRV 


RECfl 


WFLG 


00 


TRACK 


SECTOR 


BUFFAD 


BANK 


LINK 


8D 


24t) 


8b 


8b 


1Bb 


16D 


16b 


8b 


16b 



Figure 3-5. Buffer Control Block Fornat 



CP/M 3 System Guide 3.3 BIOS Data Stcuctures 

Table 3-8 describes the fields of each Buffer Control Block. 



Table 3-8. Buffer Contcol Block Fields 



Identifies the disk drive associated with the 
record contained in the buffer located at 
address BUFPAD. If you do not use GENCPM to 
allocate buffers, you must set the DRV field to 
OFFH. 

Identifies the record position of the current 
contents of the buffet located at address 
BOFFAD, REC* consists of the absolute sector 
number of the record where the first record of 
the directory is zero. 



that the 



Set by the BOOS to OFFH to indie 
buffer contains new data that has 
written to disk. When the data is 
BDOS sets the WFLG to zero to 
buffer is no longer dirty. 

Scratch byte used by BDOS. 



associated 

Contains the bank number of the buffer 
associated with this BCfl. This field is only 
present in banked systems. 

Contains the address of the next BCB in a 
linked list, or zero if this is the last BCB in 
the linked list. The LINK field is present 
only in banked systems. 



The BDOS distinguishes between two kinds of buffers; data 
buffers referenced by DTftBCB, and directory buffers referenced by 
DIHBCB. In a banked system, the DIRBCB and DTABCB fields of a Disk 
Parameter Header each contain the address of a BCB list head rather 
than the address of an actual BCB. A BCB list head is a word 
containing the address of the first BCB in a linked list. If 
several DPHs reference the same BCB list, they must reference the 
same BCB list head. Each BCB has a LINK field that contains the 
address of the next BCB in the list, or zero if it is the last BCB. 



In banked systems, the one-byte BANK field indicates the bank 
in which the data buffers are located. The BANK field of directory 
BCBs must be zero because directory buffers must be located in Bank 
0, usually below the banked BDOS module, or in common memory. The 
BANK field is for systems that support direct memory- to-memory 
transfers from one bank to another, (See the BIOS XMOVE entry point 
in Section 3.4.4. ) 

The BCB data structures in a banked system must reside in Bank 
or in conunon memory. The buffers of data BCBs can be located in 
any bank except Bank 1 (the Transient Program Area). 

upport interbank block moves 
=et to and the data buffers 
ectory buffers can be in Bank 
even if the system does not support bank-to-bank moves. 

In the nonbanked system, the DPH, DIRBCB, and DTABCB can point 
to the same BCB if the DPH defines a fixed media device. For 
devices with removable media, the DPH DIRBCB and the DPH DTABCB must 
reference different BCBs. In banked systems, the DPH DIRBCB and 
DTABCB must point to separate list heads. 

In general, you can enhance the performance of CP/M 3 by 
allocating more BCBs, but the enhancement reduces the amount of TPA 
memory in nonbanked systems. 

If you set the DPH DIRBCB or the DPH DTABCB fields to OFFFEH, 
the GENCPM utility creates BCBs, allocates physical record buffers, 
and sets these fields to the address of the BCBs. This allows you 
to write device drivers without regard to buffer requirements. 

3.3.5 Data Structure Macro Definitions 

Several macro definitions are supplied with CP/M 3 to simplify 
the creation of some of the data structures in the BIOS. These 
macros are defined in the library file CPM3.LIB on the distribution 
disk. 

To reference these macros in your BIOS, include the following 



CP/M 3 System Guide 3.3 BIOS Data Structun 



Use the DTBL macro to generate the drive table, DRVTBL. It has 
le parameter, a list of the DPHs in your system. The list Is 
iclosed in angle bcackets. 

The form of the DTBL macco call is 

label! DTBL <DPHA,DPHB DPHP> 

of the DPH for drive A, DPHB is the 
ve B, up to drive P. For example, 

DBVTBLj DTBL <ACSHDO ,FDSDO ,FDSD1> 

This example generates the drive table for a three-drive system. 
The DTBL macro always generates a sixteen-word table, even if you 
supply fewer DPH names. The unused entries are set to zero to 
Indicate the corresponding drives do not exist. 

DPH Macro 

The DPH macro routine generates a Disk Parameter Header (DPH) . 
It requires two parameters; the address of the skew table for this 
drive, and the address of the Disk Parameter Block (DPBJ. Two 
parameters are optional: the maximum size of the checksum vector, 
and the maximum size of the allocation vector. If you omit the 
maximum size of the checksum vector and the maximum size of the 
allocation vector from the DPH macro invocation, the corresponding 
fields of the Disk Parameter Header are set to OPFFEH so that GENCPM 
automatically allocates the vectors. 



The form of the DPH macro call is 




label: DPH ?trans,?dpb, [?o 


ize] ,[?as 


: 

?trans is the address of the t 


anslation 



ctor for this 

drive; 
7dpb is the address < 
?csize is the maximum size : 

vector; 
Pasize is the maximum size in bytes of the allocation 

vector. 

The following example, which includes all four parameters, 
shows a typical DPH macro invocation for a standard single-density 
disk drive: 

PDSDO: DPH SKEW6 ,DPB$SD , 16 , 31 



CP/M 3 System Guide 3.3 BIOS Data Structures 



The SKEW macro generates a skew table and requires the 
following parameters: the number of physical sectors per ttaclt, the 
skew factor, and the first sector number on each track (usually or 
L). 

The form of the SKEW macro call is 

label: SKEW ?secs,7skf ,?f sc 

Tsecs is the number of physical sectors per track; 

?skf is the sector skew factor; 

?fBC is the first sector number on each track. 

3 the skew table for a 
Ly disk drive. 

SKEH6: SKEW 26,6,1 

DPB Macro 

The DPB macro generates a Disk Parameter Block specifying the 
characteristics of a drive type. It requires six parameters: the 
physical sector size in bytes, the number of physical sectors per 
track, the total number of tracks on the drive, the size of an 
allocation unit in bytes, the number of directory entries desired, 
and the number of system tracks to reserve at the beginning of the 
drive. There is an optional seventh parameter that defines the CKS 
field in the DPB. If this parameter is missing, CKS is calculated 
from the directory entries parameter. 

The form of the DPB macro call is 

label: DPB ?psize,?pspt,?trks,7bia,7ndit3,7off [,?ncks] 

?psize is the physical sector size in bytes; 

7pspt is the number of physical sectors per track; 

7trks is the number of tracks on the drive; 

7bls is the allocation unit size in bytes; 

7ndirs is the number of directory entries; 

?off is the number of tracks to reserve; 

?noks is the nuraber of checked directory entries. 

The following example shows the parameters for a standard 
single-density disk drive: 



DPBSSD: DPB 128,26,77,1024,64,2 



CP/W 3 System Guide 



3.3 BIOS Data Stru 



The DPB macro can be used only when the disk drive is under 
_ eight megabytes. DPBs for larger disk drives must be constructed by 

3.4 BIOS Subroutine Entry Points 

I This section describes the entry parameters, returned values, 

' and exact responsibilities of each BIOS entry point in the BIOS jump 

vector. The routines are arranged by function. Section 3.4.1 

^ describes system initialization. Section 3.4,2 presents the 

I character I/O functions, followed by Section 3.4.3, discussing the 

I disk I/O functions. Section 3.4.4 discusses the BIOS memory select 

and move functions. The last section, 3.4.5, discusses the BIOS 

clock support function. Table 3-9 shows the BIOS entry points the 

"^ BDOS calls to perform each of the four categories of system 

I functions. 

._ Table 3-9. Functional Organization of BIOS Entry Points 



Operation 


Function 


System Initial 


ization 




BOOT, WBOOT, DEVTBL, DEVINI , DRVTBL, 


Character I/O 






CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN, 




LISTST, CONOST, AUXIST, AUXOST 


Disk I/O 






HOME, SELDSK, SBTTRK, SETSEC , SETDMA, 




READ, WRITE, SECTRN, MOLTIO, FLUSH 


Memory Selects 


and Moves 




HOVE, XMOVE, SELMEM, SETBNK 


Clock Support 






TIME 



Table 3-10 is 
numbers, jump instruct 
of each jump instruci 
BIOS function number. 



showing the CP/M 3 BIOS function 
, and the entry and return parameters 
le table, arranged according to the 



CP/M 3 System Guide 



3.4 BIOS Subroutine Entry points 



Table 3-10. 


CP/H 3 BIOS Functl 


on Jump Table Su»«ary 


No. 


Function 


Input 


Output 





BOOT 


None 


None 


1 


WBOOT 


None 


None 


2 


CONST 


None 


A=OPPH if ready 
A=OOH if not ready 


3 


CONIN 


None 


A=Con Char 


4 


CONOUT 


C=Con Char 


None 


5 


LIST 


C=Char 


None 


6 


AUXOUT 


C=Char 


None 


7 


AUXIN 


None 


A-Char 


8 


HOME 


None 


None 


9 


SBLDSK 


C=Drive 0-15 


HL-DPH addr 






E=lnit Sel Flag 


HL-OOOH if invalid dr. 


10 


SETTRK 


BC=Track No 


None 


11 


SETSEC 


BC-Sector No 


None 


12 


SETDMA 


BC" . DMA 


None 


13 


READ 


None 


A-OOH if no Err 

A=01H if Non-recov Err 

A=OFFH if media changed 


14 


WRITE 


C'-Deblk Code 


A=OOH if no Err 
fl-OlH if Phys Err 
A=02H if Dsk la R/O 
A=OFFH if media changed 


15 


LISTST 


None 


A=00H if not ready 
A=OFFH if ready 


16 


5ECTRN 


BC=Log Sect No 
DE=Tran3 Tbl Adr 


HL=Phys Sect No 


17 


CONOST 


None 


A=OOH if not ready 
A=OFFH if ready 


18 


AUXIST 


None 


A=OOH if not ready 
A=OPPH if ready 


19 


AUXOST 


None 


A«0OH if not ready 
A=OFPH if ready 


20 


DEVTBL 


None 


HL=Chrtbl addr 


21 


DEVINI 


C=Dev No 0-15 


None 


22 


DRVTBL 


None 


HL=Drv Tbl addr 

HL=OFFFFH 
HL=OFFFEH 


23 


MULT 10 


C=Mult Sec Cnt 


None 


24 


PLUSH 


None 


A=OOOH if no err 
A=001H if phys err 
A=002H if disk R/O 


25 


MOVE 


HL=Dest Adt 


HL & DE point to next 






DE=Source Adr 


bytes following MOVE 






BC=Count 




26 


TIME 


C=Get/Set Flag 


None 


27 


SELMEM 


A=Mein Bank 


None 


28 


SETBNK 


A=Mem Bank 


None 


29 


XMOVE 


B=Dest Bank 
C=Source Bank 


Hone 



CP/M 3 System Guide 







Table 3-10. (continued} 


No. 


Function 


Input 


3D 
31 
32 


OSERP 

RESERVl 

RESERV2 


Reserved for System Implementor 
Reserved for Future Use 
Reserved for Future Use 



3.4.1 System Initialization Functions 





BIOS 


Function 


BOOT 


Get 


Control 
and 


from Cold 
Initialize 


Start Loader 
System 




Entry 
Retur 


Parametecs! None 
ned Values: None 



The BOOT entry point gets control from the Cold Start Loader in 
Bank and is responsible for basic system initialization. Any 
remaining hardware initialization that is not done by the boot ROMs, 
the Cold Boot Loader, or the LDBBIOS should be performed by the BOOT 



The BOOT routine must perform the system initialization 
outlined in Section 2.3, "System Initialization." This includes 
initializing Page Zero jumps and loading the CCP. BOOT usually 
prints a sign-on message, but this can be omitted. Control is then 
transferred to the CCP in the TPA at OlOOH. 

To initialize Page Zero, the BOOT routine must place a jump at 
location OOOOH to BIOS_base + 3, the BIOS warm start entry point. 
The BOOT routine must also place a jump instruction at location 
0005H to the address contained in the System Control Block variable, 
ewXTPA . 



The BOOT routine 
any BDOS or BIOS routi 
when the Cold BOOT i 



stablish its own stack area if it calls 
n a banked system, the stack is in Bank 
is entered. The stack must be placed 



CP/M 3 System Guide 



System Initialization Functii 



BIOS Function 1: 


WBOOT 


Get Control When a Warm 


Start Occurs 


Entry Parameters; 
Returned Values: 


None 
None 



The WBOOT entry point is entered when a warm start occurs. A 
warm start is performed whenever a user program branches to location 
OOOOH or attempts to return to the CCP. The WBOOT routine must 
pet form the system initialization outlined in BIOS Function , 
including initializing Page Zero jumps and loading the CCP. 



it must transfer 



mtrol 



Note that the CCP does not reset the disk system at warm start. 
The CCP resets the disk system when a CTRL-C is pressed following 
the system prompt. 

Note also that the BIOS stack must be in common memory to make 
BDOS function calls. Only the BOOT and WBOOT routines can perform 
BDOS function calls. 

If the WBOOT routine is reading the CCP from a file, it must 
set the multisector I/O count, @MLTIO in the System Control Block, 
to the number of 128-byte records to be read in one operation before 
reading CCP.COM. You can directly set gMLTIO in the SCB, or you can 
call BDOS Function 44 to set the multisector count in the SCB. 

le in the BIOS instead of in the 
ird ail pending buffers. 





BIOS Fun 


=ti 


on 20: 


DEVTBL 


Retu 


rn Address 


of 


Charac 


ter I/O Table 


Entry 

Retur 


Parameter 
ned Values 




None 
HL-add 


cess of Chrtbl 



The DEVTBL and DEVINI entry points allow you to support device 
assignment with a flexible, yet completely optional system. It 
replaces the lOBYTE facility of CP/M 2.2. Note that the CHRTBL must 
I in banked systems. 



^ CP/M 3 System Guii 



System Initiali: 



BIOS Function 21: DEVINI 



Initialize Character I/O Device 



Entry Parameters: C=device number , 0-15 
Returned Values: None 



The DEVINI routine initializes the physical character device 
specified in register C to the baud rate contained in the 
appropriate entry of the CHRTBL. It need only be supplied if I/O 
redirection has been implemented and is referenced only by the 
DEVICE utility supplied with CP/M 3. 



BIOS Function 22: DRVTBL 



Return Address of Disk Dri 



Entry Parameters: 
Returned Values: 



None 

[iLxAddress of Dr ive Table of Disk 

Parameter Headers (DPH) ; Hashing can 

be utilized if specified by the DPHs 

referenced by this DRVTBL. 
HL=OFFFFH if no Drive Table; GENCPM does 

not set up buffers. Hashing Is 

supported. 
HL-OFFFEH if no Drive Table; GENCPM does 

not set up buffers. Hashing is not 

supported. 



The first instruction of this subroutine must be an LXI 
H , <address> where <address> is one of the above returned values. 
The GENCPM utility accesses the address in this instruction to 
locate the drive table and the disk parameter data structures to 
determine which system configuration to use. 

L blocking/deblocking, the first 
! must be the following: 



and PSM fields of the 



issociated Dii 



CP/« 3 System Guide 



Character I/O Functit 



3.4.2 Character I/O Functions 

This section defines the CP/M 3 character I/O routines CONST, 
CON IN , CONOUT , LIST , AUXOOT , AUXIN , LISTST, CONOST, RUXIST , and 
AUXOST. 



CP/M 3 assumes all simple 
performed in eight-bit ASCII, upper- 
An ASCII CTRL-Z (lAH) denotes an en* 



character I/O operations are 
and lowercase, with no parity. 
-o£-file condition for an input 



In CP/M 3, you can direct each of the five logical charactei: 
devices to any combination of up to twelve physical devices. Each 
of the five logical devices has a 16 -bit vector in the System 
Control Block (SCB) . Each bit of the vector represents a physical 
device where bit 15 corresponds to device zero, and bit 4 is device 
eleven. Bits through 3 are reserved for future system use. 

You can use the public 
file to reference the I/O r« 
shown in Table 3-11. 



Table 3-11. I/O Redirection Bit Vectors : 



ecivEc 

gCOVEC 
@AIVEC 
eAOVEC 

§LOVEC 



Logical Device 

Console Input 
Console Output 
Auxiliary Input 
Auxiliary Output 
List Output 



You should send an output character to all of the devices whose 
responding bit is set. An input character should be read from 
■ first ready device whose corresponding bit is set. 



if all selei 



put status routine should return true 


if any selected 


eady. An output status routine should 


return true only 


acted devices are ready. 





CP/M 3 System Guide 



Character I/O Punctit 





BIOS 


Function 


2: 


CONST 








Sample 


the Sta 


tus of th 


e Console Input Dev 


c. 


Entry Pa 
Returned 


rameter 


s; None 

A=OFFH 

is r 

A=OOH 


if a cc 
eady to 
if no cc 
eady to 


nsole 
read 
nsole 
read 


cha 
cha 


acter 
acter 



Head the status of the curti 
return OFFH in register A if a ch, 
in register A if no console chaci 



tly assigned con 


sole device and 


acter is ready t 


) read, and OOH 


ters are ready. 









BIOS Funct 


ion 3: 


CON IN 




Read 


a Chatacte 


from 


the 


Console 


Entry Pa 
Returned 


rameters: 
Values: 


None 
A'Console 


Character 



Read the next console character into register A with no parity, 
IE no console character is ready, wait until a character is 
available' before returning. 



BIOS Function 4: CONOUT 



Output Character to Console 

Entry Parameters: C=Console Chara( 
Returned Values: None 



3ter in register C to the console output device. 
I ASCII with no parity. 



CP/M 3 System Guide 



Character I/O Functioi 



BIOS Function 5: LIST 

Output Character to List Device 

Entry Parametera; C''Chatacter 
Returned Values: None 



Send the character from register C to the Listing device. The 
character is in ASCII with no parity. 



BIOS Punctior 


€'. 


AUXOUT 


Output a Cha 
Auxiliary 


acter to the 
tput Device 


Entry Pa 
Returned 


ameters: 
Values: 


C=Chacacteir 
None 



Send the character from register C to the currently assigned 
AUXOUT device. The character is in ASCII with no parity. 



BIOS Function 7; 


AUXIN 


Read a Character 
Auxiliary Input 


from the 
Device 


Entry Parameters: 
Returned Values: 


None 
R-Char acter 



Read the next character from the currently assigned AUXIN 
device into register A with no parity. A returned ASCII CTRL-Z 
(lAH) reports an end-of-file. 



CP/M 3 System Guide 



Character I/O Puncti( 



BIOS Function 15: USTST 



Retucn the Ready status of the List Devii 



Entry Parameters: None 



Returned Values; 



A-OOOH If List device is not 
ready to accept a character 

R-OFPH if list device is 
ready to accept a character 





BIOS Funct 


on 17! 


CONOST 




Retu 


n Output 


Status 


of Console 


Entry Pa 
Returned 


ameters: 
Values: 


None 

ft=OFFH 
R-OOH 


if ready 

if not ready 



The CONOST routine checks the status of the console. CONOST 
rns an OPPH if the console is ready to display another 
acter. This entry point allows for full polled handshaking 
tions support. 



BIOS Functi 


on 18: AUXIST 


Return Input Stat 


us of Auxiliary Port 


Entry Parameters: 
Returned Values: 


None 

A=OFFH if ready 
A=OOOH if not ready 



The AUXIST routine checks the input status of the auxiliary port. 
This entry point allows full polled handshaking for communications 
support using an auxiliary port. 



CP/M 3 System Guide 



Character I/O Functions 



BIOS Funct 


on 19: RUXOST 


Return Output St 


tus of Auxiliary Poet 


Entry Parameters 
Returned Values: 


None 

A-OFFH if ready 
A=OODH if not ready 



The AUXOST routine checks the output status of the auxiliary 
port. This routine allows full polled handshaking for 
nications support using an auxiliary port. 



3.4.3 Disk I/O Functions 

This section defines the CP/M 3 BIOS disk I/O routines HCWE, 
SELDSK, SETTRK, SETSEC, SETDMA , READ, WRITE, SECTRK , MULTIO , and 
FLUSH. 





BIOS 


Fun 


:t 


o„8: 


HOKE 




Select 


Track 


00 


of 


the Specified 


Drive 




Entry Pa 

Returned 


rameters: 
Values! 


None 

None 





Return the disk head of the currently selected disk to the 
lok 00 position. Usually, you can translate the HOME call into a 
.1 on SETTRK with a parameter of 0. 



>— CP/M 3 System Gu: 



Disk I/O Funct. 



Select the Specified Disk Drive 



Returned Valui 



HL=Address of Disk Parameter 

Header (DPH) if drive exis 
HL=O00H if drive does not exi; 



Select the disk drive spe' 
operations, where register C con 
and so on to 15 for drive P. 
return in HL the base address c 
Parameter Header. If there is e 
drive, SELDSK returns HL=OOOOH c 



ther 



;i£ied in register C for f u 
;ains for drive A, 1 for dri 
On each disk select, SELDSK 
£ a 25-byte area called the 
n attempt to select a nonexistei 



indie 



ator, 



On entry to SELDSK, you can determine if it is the first tii 
the specified disk is selected. Bit 0, the least significant bit : 
register E, is set to if the drive has not been previous! 
selected. This information is of interest in systems that re, 
configuration information from the disk to set up a dynamic di: 
definition table. 



When the BDOS calls SELDSK w 
SELDSK must return the same Dis 
returned on the initial call to th 
OOOa indicating an unsuccessful 



th bit in register E set to 1, 
: Parameter Header address as it 
} drive. SELDSK can only return a 
lelect on the initial select call 



SELDSK must return the address of the Disk Parameter Header oi 
each call. Postpone the actual physical disk select operation unti: 
a READ or WRITE is performed, unless I/O is required for automatii 
density- sensing. 



BIOS Function 


10 : SETTRK 


Set Specified 


Track Number 


Entry Parameters: 
Returned Values: 


BC=TEack Number 
None 



Register BC contains the trat 
access on the currently selected dr 
is saved until the next HT " 



number for a subsequent disk 
!. Normally, the track number 
WRITE occurs. 



CP/M 3 System Guide 



Disk I/O Functii 





BIOS Function 


11: 


SETSEC 




Set Specified 


Secto 


Number 


Entry Pa 
Returned 


ameters: 
Values: 


BC=Sector Number 
None 



Register BC contains the sector number for the subsequent disk 
access on the currently selected drive. This number is the value 
returned by SECTRN. Usually, you delay actual sector selection 
until a READ or WRITE operation occurs. 



BIOS 


Functic 


n 12! SETDMA 


Set Address for 


Subsequent Disk I/O 


Entry Pa 
Returned 


ametera 
Values 


! BC=Direct 
Access 

None 


Memory 
Address 



Register BC contains the DMA (Direct Memory Access) address for 
the subsequent READ or WRITE operation. For example, if B = OOH and 
C = 80H when the BDOS calls SETDMA, then the subsequent read 
operation reads its data starting at 80H, or the subsequent write 
o-^ecation gets its data from BOH, until the next call to SETDMA 



r— CP/M 3 Syateiti Guide 



Disk I/O Functions 







BIOS 


Functior 


13: READ 








Read a Sector 


from tt 


e Specified Drive 




Entry Pa 


ameters: 


None 








Retur 


ned 


Values: 


A=OOOH 


if no erro 


3 occur 


red 








A^OOIH 


if nonrecov 


erable 


error 








condi 


tion occur 


ed 










A-OPFH 


if media has chang 


ed 



Assume the BDOS has selected the drive, set the track, set the 
sector, and specified the DMA address. The READ subroutine attempts 
to read one sector based upon these parameters, then returns one of 
the error codes in register A as described above. 



then CP/M 3 assumes that the 
E an error occurs, the BIOS 
if the error is recoverable 



If the value in register A is 
disk operation completed properly, 
should attempt several retries to s 
before returning the error code. 

If an error occurs in a system that supports automatic density 
selection, the system should verify the density of the drive. If 
the density has changed, return a OFFB in the accumulator. This 
causes the BDOS to terminate the cutrent operation and uelog in the 
disk. 



BIOS Function 14: WRITE 


Write a Sector to the Specified Disk 




Entry Parameters: C=Deblocking Codes 

Returned Values: A=OOOH if no error occurred 

A=001H if physical error oocu 
A-002H if disk is Read-only 
A=OFFH if media has changed 


red 



Write the data from the currently selected DMA address to the 
currently selected drive, track, and sector. Upon each call to 
WRITE, the BDOS provides the following information in register C: 

= deferred write 

1 = nondeferred write 

2 = deferred write to the first sector of a new data block 



CP/M 3 System Guide 



Disk I/O Funct: 



This information is provided for those BIOS implementations that do 
blocking/deblocking in the BIOS instead of the BDOS . 

As in READ, the BIOS should attempt several retries before 
reporting an error. 

If an error occurs in a system that supports automatic density 
selection, the system should verify the density of the drive. If 
the density has changed, return a OFFH in the accumulator. This 
causes the BDOS to terminate the current operation and relog in the 



Translate Sector Number Given Translate Tabli 

Entry Parameters: BC=Logical Sector Number 
DE=Translate Table Addres; 

Returned Values! HL=Physical Sector Number 



SECTHN performs logical sequential sector address to physical 
sector translation to improve the overall response of CP/M 3. 
Digital Research ships standard CP/M disk with a skew factor of 6, 
where six physical sectors are skipped between each logical read 
operation. This skew factor allows enough time between sectors for 
most programs on a slow system to process their buffers without 
missing the next sector. In computer systems that use fast 
processors, memory, and disk subsystems, you can change the skew 
factor to improve overall response. Typically, most disk systems 
perform well with a skew of every other physical sector. You should 
maintain support oE single-density, IBM 3740 compatible disks using 
a skew factor of 6 in your CP/M 3 system to allow information 
transfer to and from other CP/M users. 

SECTHN receives a logical sector number in BC, and a translate 
table address in OE. The logical sector number is relative to zero. 
The translate table address is obtained from the Disk Parameter 
Block for the currently selected disk. The sector number is used as 
an index into the translate table, with the resulting physical 
sector number returned in HL. For standard, single-density, eight- 
inch disk systems, the tables and indexing code are provided in the 
sample BIOS and need not be changed. 



Certain drive types 
skewing externally from t 
table address in the DPH ■ 
can check for the zero in 
to the logical sector. 



either do not need ske- 



ing . 



c perforr 



the 



— CP/M 3 System Guide 



sk 1/0 Functions 



BIOS Functic 



Set Count of Consecutive Sectors 
Eor HEAD or WRITE 



Entry Parameters! C=Multisector Count 
Returned Values: None 



To transfer logically consecutive disk sectors to or from 
contiguous memory locations, the BDOS issues a MULTIO call, followed 
by a series of READ or WRITE calls. This allows the BIOS to 
transfer multiple sectors in a single disk operation. The maximum 
value of the sector count Is dependent on the physical sector size 
ranging from 128 with 12e-byte sectors, to 4 with 4096-byte sectors 
Thus, the BIOS can transfer up to 16K directly to or from the Tpa 
with a single operation. 



The BIOS can directly 
or from the DMA buffer ir 
ceraainlng calls to read or WRITE 



:ransfet all of the specified sectors to 
one operation and then count down the 



skew table to j 



If the disk format uses 
latency when single records are transferred, it is more 
optimize transfer time for multi sector transfers, 
utilizing the multisector count with a skewed disk 
place the sector numbers and associated DMA addresses into a table 
until either the residual multisector count reaches zero, or the 
track number changes. Then you can sort the saved requests by 
physical sector to allow all of the required sectors on the track to 
be read in one rotation. Each sector must be transferred to or from 
Its proper DMA address. 

When an error occurs during a multisector transfer, you can 
either reset the multiple sector counters in the BIOS and return the 
error immediately, or you can save the error status and return it to 
the BDOS on the last READ or WRITE call of the MULTIO operation. 



e rotational 
difficult to 
One way of 
format is to 
into c 



Disk I/O Functi( 



BIOS Function 24: FLUSH 


Force Physical Buffet Flushing 
for User-supported Deblocking 


Entry Parameters: None 

Returned Values: A=OOOH if no error occurred 

A=001H if physical error occl 
A=002H if disk is Read-only 


rred 



nt allows the system to force 
^ your BIOS is performing its own 



no dirty 



The flush buffets entry poi 
physical sector buffet flushing whe 
record blocking and deblocking. 

The BDOS calli 
buffers remain in mi 
buffets that contain unwtitten dat. 

Kotmally, the FLUSH function is superfluous, because the BDOS 
supports blocking/deblocking internally. It Is required, however, 
for those systems that support blocking/deblocking in the BIOS, as 
many CP/M 2.2 systems do. 

Bote: if you do not implement FLUSH, the routine must return a zero 
in register A. You can accomplish this with the following 



3.4.4 Henory Select and Hove Functions 



This section defines the 
XMOVE, SELMEM, and SETBNK. 



try management fui 



CP/M 3 System Guide 



Memory Select and Move Fui 



BIOS Function 25; MOVE 


Memory-t 


o-Memory Block Move 


Entry Parameters: 
Returned Values: 


HL=Destination address 
DE=Source address 
BC=Count 

HL and DE must point to 
next bytes following move 
operation 



The BDOS calls the MOVE routine to perform memory to memory 
block moves to allow use of the 380 LDIR instruction or special DMA 
hardware, if available. Note that the arguments in HL and DE are 
reversed from the Z80 machine instruction, necessitating the use of 
XCHG instructions on either side of the LDIR. The BDOS uses this 
routine foe all large memory copy operations. On return, the HL and 
DE registers are expected to point to the next bytes following the 

Usually, the BDOS expects MOVE to transfer data within the 
currently selected bank or common memory. However, if the BDOS 
calls the XMOVE entry point before calling MOVE, the MOVE routine 
must perform an interbank transfer. 



CP/M 3 System Guide 



Memory Select and Move Functions ^ 



BIOS Function 27: SELMEH 



Select Memory Bank 



Entry Parameters: A-Memory Bank 
Returned Values; None 



The SELMEM entry point la only present in banked systems. The 
banked version of the CP/M 3 BOOS calls SELMEM to select the current 
memory bank for further instruction execution or buffer references. 
You must preserve or restore all registers other than the 
accumulator, A, upon exit. 



BIOS Function 


28: SETBNK 


Specify 


Bank for 


DMA operation 


Entry Pa 
Returned 


ameters! 
Values: 


A=Memory Bank 
None 



SETBNK only occurs in the banked version of CP/M 3. SETBNK 
specifies the bank that the subsequent disk READ or WRITE routine 
must use for memory transfers. The BDOS always makes a call to 
SETBNK to identify the DMA bank before performing a READ or WRITE 
call. Note that the BDOS does not reference banks other than or 1 
unless another bank is specified by the BANK field of a Data Buffet 
Control Block (BCB) . 



BIOS Function 29: XMOVE 


Set Banks for 


Following MOVE 


Entry Parameters: 
Returned Values: 


B=destination bank 
C=source bank 

None 



XMOVE is provided for banked systems that support memory-to- 
memory DMA transfers over the entire extended address range. 
Systems with this feature can have their data buffers located in an 



^ CP/M 3 System Guide 



Memory Select and Move Functions 



alternate bank Instead of in coininon memory, as is usually required. 
An XMOVE call affects only the following MOVE call. All subsequent 
MOVE calls apply to the memory selected by the latest call to 
SELMEM. After a call to the XMOVE function, the following call to 
the MPVE function is not more than 128 bytes of data. If you do not 



Implement XMOVE, the first instructioi 



lust be ■ 



RET . 



ctio] 



3.4.5 Clock Support Function 

This section defines the clock support function TIME. 





BIOS Function 26: 


TIME 






Get and 


Set Tim 






Entry Parameters! 
Returned values: 


C-Time 
None 


Get/Set 


Flag 



The BDOS calls the TIME function to indicate to the BIOS 
whether it has just set the Time and Date fields in the SCB, or 
whether the BDOS is about to get the Time and Date from the SCB. On 
entry to the TIME function, a zero in register C indicates that the 
BIOS should update the Time and Date fields in the SCB. A OFFH in 
register C indicates that the BDOS has just set the Time and Date in 
the SCB and the BIOS should update its clock. Upon exit, you must 
restore register pairs HL and DE to their entry values. 

This entry point is for systems that must interrogate the clock 
to determine the time. Systems in which the clock is capable of 
generating an interrupt should use an interrupt service routine to 
set the Time and Date fields on a regular basis. 



3.5 Banking Considerations 

This section discusses consider, 
into resident and banked modules, 
customized BIOS in common memory 
However, the following data structur 
common memory: 



:ions for separating 
You can place part 
and part of it in 

3 and routines must 



your BIOS 
Bank 0. 



the BIOS stack 
the BIOS jump vector 
Disk Parameter Blocks 
memory management routine, 
the CHRTBL data structure 
all character I/O routine; 
portions of the disk I/O 



CP/M 3 System Guide 3.5 Banking Considerations 

You can place portions of the disk I/O routines in the syatan 
bank, Bank 0. In a banked environment, i£ the disk I/O hardware 
supports DMA transfers to and from banks other than the currently 
selected bank, the disk I/O drivers can reside in Bank 0. If the 
system has a DMA controller that supports block moves from memory to 
memory between banks, CP/M 3 also allows you to place the blocking 
and deblocking buffers in any bank other than Bank 1, instead of 



IE your disk controller supports data transfers only into the 
currently selected bank, then the code that initiates and performs a 
data transfer must reside in common memory. In this case, the disk 
I/O transfer routines must select the DMA bank, perform the 
transfer , then teselect Bank 0, The routine in common memory 
performs the following procedure: 

1) Selects the DMA bank that SETBNK saved. 

2) Performs physical I/O, 
3} Reselects Bank 0. 

i) Returns to the calling BEAD or WRITE routine in Bank 0. 

Note that Bank Is in context (selected) when the BDOS calls 
the system initialization functions BOOT and DRVTBLr the disk I/O 
routines HOME, SELDSK, SETTRK, SETSEC, SETDMA, READ, WRITE, SECTRN , 
MULTIO, and FLUSHr and the memory management routines XMOVE and 

SETBNK . 

Bank or Bank 1 is in context when the BDOS calls the system 
initialization routines WBOOT, DEVTBL, andDEVINI; the character I/O 
routines CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN, LISTST , CONOST , 
AUXIST, and AUXOST, the memory select and move routines MOVE and 
SELMEM, and the clock support routine TIME. 

You can place a portion of the character I/O routines in Bank 
If you place the following procedure in common memory. 

1) Swap stacks to a local stack In common. 

2) Save the current bank. 

3) Select Bank 0. 

4] Call the appropriate character I/O routine. 
5) Reaelect the saved bank. 
6] Restore the stack. 



'^ CP/M 3 System Guide 3.G Assembling and Linking Your BIOS 

3.6 ABseabltng and Linking Zour BIOS 

This section assumes you have developed a BI0S3 .ASM ot: 
BHKBI0S3 .ASM file appropriate to your specific hardware environment. 
Use the Digital Research Relocatable Macro Assembler RHAC™ to 
^ assemble the BIOS. Use the Digital Research Linker LINK-80™ to 
create the BI0S3.SPR and BNKBIOS3.SPR files. The SPR files are part 
of the input to the GENCPM program. 

In a banked environment, your CP/M 3 BIOS can consist of two 
"~ segments: a banked segment and a common segment. This allows you 
to minimize common memory usage to maximize the size of the TPA. To 
prepare a banked BIOS, place code and data that must reside in 
common in the CSEG segment, and code and data that can reside in the 
„ system bank in the DSEG segment. When you Link the BIOS, LINK-90 
creates the BNKBI0S3.SPR file with all the CSEG code and data first, 
then the DSEG code and data. 

After assembling the BIOS with RHAC, link youc BNKBIOS using 
— LINK-80 with the [B] option. The [B] option aligns the DSEG on a 
page boundary, and places the length of the CSEG into the 
BNRBI0S3.SPR header page. 

sdure to prepare a BI0S3.SPR or 



1) Assemble youc BI0S3.ASH or BNKBI0S3.ASM file with the 
relocatable assembler RMAC.COM to produce a relocatable 
file of type REL . Assemble SCB .ASM to produce the 
relocatable file SCB. REL, 

Assembling the Nonbanked BIOS: 

A>RHAC BIOS 3 

Assembling the Banked BIOS: 

A>RMAC BNKBIQS3 

2) Link the BIOS3.REL or BNKBI0S3.REL file and the SCB. REL file 
with LINK-BO to produce the BIOS3.SPR or BNKBI0S3.SPR file. 
The [OS] option with LINK causes the output of a System 
Page Relocatable (SPR) file. 

Linking the Nonbanked BIOS: 

A>LINK BIOS3|05]'>BIOS3,SCB 

Linking the Banked BIOS: 

A>LIHK BNKBZOS3[B]-BliKBIOS3,SCB 



CP/M 3 System Guide 3.6 Assembling and Linking Your BIOS 

The preceding examples show command lines for linking a banked 
and nonbanked BIOS. In these examples, the BIOS 3 .REL and 
BNKBI0S3.REL are the files of your assembled BIOS. SCB.REL contains 
the definitions of the System Control Block variables. The [B] 
option implies the [OS] option. 

End of Section 3 



Section 4 
CP/M 3 Sample BIOS Modules 



This section discusses the modular organization of the example 
CP/M 3 BIOS on your distribution disk. For previous CP/M operating 
systems, it was necessary to generate all input/output drivers from 
a single assembler source file. Such a file is difficult to 
maintain when the BIOS supports several peripherals. As a result. 
Digital Research is distributing the BIOS for CP/M 3 in several 
small modules. 

The organization of the BIOS into separate modules allows you 
to write or modify any I/O driver independently of the other 
modules. Foe example, you can easily add another disk I/O driver 
for a new controller with minimum impact on the other parts of the 
BIOS. 

4.1 Functional Sugary of BIOS Hodules 

The modules of the BIOS are BIOSKRNL.ASM, SCB.ASM, BOOT. ASH, 
MOVE.ASM, CHARIO.ASM, DRVTBL.ASM, and a disk I/O module for each 
supported disk controller in the configuration, 

BIOSKRNL.ASM is the kernel, root, or supervisor module of the 
BIOS. The SCB.ASM module contains references to locations in the 
System Control Block. You can customize the other modules to 
support any hardware configuration. To customize your system, add 
or modify external modules other than the kernel and the SCB.ASM 
module. 

Digital Research supplies the BIOSKRNL.ASM module. This module 
is the fixed, invariant portion of the BIOS, and the interface from 
the BDOS to all BIOS functions. It is supplied in source form for 
reference only, and you should not modify it except for the equate 
statement described in the following paragraph. 

You must be sure the equate statement (banked equ true} at the 
start of the BIOSKRNL.ASM source file is correct for your system 
configuration. Digital Research distributes the BIOSKRNL.ASM file 
for a banked system. If you are creating a BIOS for a nonbanked 
system, change the equate statement to the following: 

banked equ false 

This is the only change you should make 



Table 4-1 summarizes the modules in the CP/M 3 BIOS. 



CP/M 3 System Guide 4.1 Functional Summary of BIOS Modules 
Table 4-1. CP/M 3 BIOS Module Puiiction Suaiuiry 



Module 



Funct 



BIOSKRNL.ASM 



Performs basic system initialization, and 
dispatches character and disk I/O, 



SCB.ASM module 



Contains the public definitions of the 
various fields in the System Control Block. 
The BIOS can reference the public variables. 



BOOT. ASM module 



Performs system initialization other than 
character and disk I/O. BOOT loads the CCP 
for cold starts and reloads it for warm 
starts. 



CHARIO.ASM module 



Performs all character device initialization, 
input, output, and status polling. CHARIO 
contains the character device characteristics 
table. 



DRVTBL.ASM module 



Points to the data structures for each 
configured disk drive. The drive table 
determines which physical disk unit is 
associated with which logical drive. The 
data structure for each disk drive is called 
an Extended Disk Parameter Header (XDPH) . 



Disk I/O modules 



Initialize disk controllers and execute READ 
and WRITE code for disk controllers. You 
must provide an XDPH for each supported unit, 
and a separate disk I/O module for each 
controller in the system. To add another 
disk controller for which a prewritten module 
exists, add its XDPH names to the DRVTBL and 
link in the new module. 



CP/H 3 System Guide 4.1 Functional Summary of BIOS Modulei 
Table 4-1. (continued) 



Module 


Function 












MOVE. ASM 


module 

Performs 
selects. 


memocy-to-me 


mory 


.oves 


and 


bank 



4.2 Conventions Dsed in BIOS Modules 

The Digital Research RMAC relocating assembler and LINK-80 
linkage editor allow a module to reference a symbol contained in 
another module by name. This is called an external reference. The 
Microsoft* relocatable object module format that RMAC and LINK use 
allows six-character names for externally defined symbols. External 
names must be declared PUBLIC in the module in which they are 
defined. The external names must be declared BXTRN in any modules 
that reference them. 

The modular BIOS defines a number of external names for 
specific purposes. Some of these are defined as public in the root 
module, BIOSKRNL.ASM. Others ate declared external in the root and 
must be defined by the system implementor. Section 4.4 contains a 
table summarizing all predefined external symbols used by the 
modular BIOS. 

External names can refer to either code or data. All 
predefined external names in the modular BIOS prefixed with a @ 
character refer to data items. All external names prefixed with a ? 
character refer to a code label. To prevent conflicts with future 
extensions, user-defined external names should not contain these 
characters. 

4.3 Interactions of Nodules 

The root module of the 1 
, performs interfacing fui 

4.3.1 Initial Boot 



.ry point of each XDPH in the 



CP/M 3 System Guide 4.3 Interactions of Modules 

3) BIOSKRNL calls the 7INIT entry of the BOOT module to 
initialize other system hardware, such as meraocy 
controllers, interrupts, and clocks. It prints a sign-on 
message specific to the system, if desired. 



5) The BIOSKRNL module sets up Page Zero of the TPA with the 
appropriate jump vectors, and passes control to the CCP. 

4.3.2 Character I/O Operation 

The CHARIO module performs all physical character I/O, This 
module contains both the character device table (§CTBL) and the 
routines for character input, output, initialization, and statuB 
polling. The character device table, @CTBL, contains the ASCII name 
of each device, mode information, and the current baud rate of 
serial devices. 

To support logical to physical redirection of character 
devices, CP/M 3 supplies a 16-bit assignment vector for each logical 
device. The bits in these vectors correspond to the physical 
devices. The character I/O interface routines in BIOSKRNL handle 
all device assignment, calling the appropriate character I/O 
routines with the correct device number. The BIOSKRNL module also 
handles XON/XOFF processing on output devices where it is enabled. 

You can use the DEVICE utility to assign several physical 
devices to a logical device. The BIOSKRNL root module polls the 
assigned physical devices, and either reads a character from the 
first ready input device that is selected, or sends the character to 
all of the selected output devices as they become ready, 

4.3.3 Disk I/O Operation 

The BIOSKRNL module handles all BIOS calls associated with disk 
I/O. It initializes global variables with the parameters for each 
operation, then invokes the READ or WRITE routine for a particular 
controller. The SELDSK routine in the BIOSKRNL calls the LOGIB 
routine for a controller when the BDOS initiates a drive login. 
This allows disk density or media type to be automatically 
determined. 

The DRVT8L module contains the sixteen-word drive table, ^DTBL, 
The order of the entries in eOTBL determines the logical to physical 
drive assignment. Each word in @DTBL contains the address of a DPH, 
which is part of an XDPH, as shown in Table 4-10, The word contains 
a zero if the drive does not exist. The XDPH contains the addresses 
of the INIT, LOGIN, READ, and WRITE entry points of the I/O driver 
for a particular controller. When the actual drivers are called, 
globally accessible variables contain the various parameters of the 
operation, such as the track and sector. 



4.4 Predefined Variable: 



4.4 Predefined Variables and Subroutines 

The modules of the BIOS define publii 
modules can reference. Table 4-2 contains i 
symbol and the module that defines it. 



ables which other 
ary of each public 



Table 4-2. Public SyHbols 







Defined 


Symbol 


Function and Use 


in Module 


eADRV 


Byte, Absolute drive code 


BIOSKRNL 


8CBNK 


Byte, Current CPU bank 


BIOSKRNL 


@CNT 


Byte, Multisector count 


BIOSKRNL 


eCTBL 


Table, Character device table 


CHARIO 


eOENK 


Byte, Bank for disk I/O 


BIOSKRNL 


@DMA 


Word, DMA address 


BIOSKRNL 


eOTBL 


Table, Drive table 


DRVTBL 


§RDRV 


Byte, Relative drive code (UNIT) 


BIOSKRNL 


gSECT 


Word, Sector address 


BIOSKRNL 


gTRK 


Word, Track number 


BIOSKRNL 


?BANK 


Bank select 


MOVE 


?CI 


Character device input 


CHARIO 


?CINIT 


Character device initialization 


CHARIO 


?CIST 


Character device input status 


CHARIO 


?C0 


Character device output 


CHARIO 


?COST 


Character device output status 


CHARIO 


7INIT 


General initialization 


BOOT 


7LDCCP 


Load CCP for cold start 


BOOT 


?MOVE 


Move memory to memory 


MOVE 


7PDEC 


Print decimal number 


BIOSKRNL 


7FDERR 


Print BIOS disk error header 


BIOSKRNL 


7PMSG 


Print message 


BIOSKRNL 


7RLCCP 


Reload CCP for warm start 


BOOT 


7XM0VE 


Set banks for extended move 


MOVE 


7TIME 


Set or Get time 


BOOT 



The System Control Block defines public vpriables that other 
modules can reference. The System Control Block variables eciVEC, 
€COVEC, eAIVEC, eAOVEC, and gLOVEC are referenced by BIOSKRNL. ASM. 
The variable gBNKBF can be used by 7LDCCP and 7RLCCP to implement 
interbank block moves. The public variable names §ERMDE, gFX, 
@RESEL, eviNFO, ^CRDSK, gUSRCD , and ?CRDMA are used for error 
routines which intercept BDOS errors. The publics ^DATE, gHOUR, 
be updated by an interrupt-dr iven real-time 
ains the current BDOS entry point. 



par; 



leter: 



ire pass.ed in the following 



CP/M 3 System Guii 



4.4 Predefined Vaciablea and Subrt 



Table 4-3. Global Variables in BIOSKBNL.ASH 

Le Meaning 

Byte; contains the absolute drive code (0 
through F for A through P) that CP/M is 
referencing for READ and WRITE operations. The 
SELDSK routine in the BIOSKRNL module obtains 
this value from the BDOS and places it in gDRV. 
The absolute drive code is used to print error 

Byte; contains the relative drive code for READ 
and WRITE operations. The relative drive code 
is the UNIT number of the controller in a given 
disk I/O module. BIOSKRNL obtains the unit 
number from the XDPH. This is the actual drive 
code a driver should send to the controller. 

i the starting track for READ and 
1 the starting sector for HEAD and 



rting disk trai 



e-CRK 


word; conta 
WRITE. 


eSECT 


Word; conta 

WRITE. 


eOMA 


Word; cont 
address. 


@DBHK 


Byte; conta 


eCNT 


Byte; conta 
the operati 



ns the bank of the DMA buffer 



nk for code 



the BIOSKRNL.ASM 



Table 


4-4. Public Dtillty Subroutines in BIOSKHHL.ASM 


Utility 


1 Meaning 


?PMSG 


Print string starting at <HL>, stop at null 
(0). 


7PDEC 


Print binary number in decimal from HL. 


7PDERR 


Print disk error message header using current 
disk parameters: <CR><LF>BIOS Error on d: , T- 
nn, S-nn. 



CP/M 3 System Guide 



4.4 Predefined Variables and Subroutines 



All BIOS entry points in the jump vector are declared as public 
for general reference by other BIOS modules, as shown in Table 4-5. 



Table 4-5. 


Public Names in the BIOS Jump Vector 


Public Name 


Function 


?BOOT 


Cold boot entry 


7WBQOT 


Warm boot entry 


7C0NST 


Console input status 


? CON IN 


Console input 


?CONO 


Console output 


?LIST 


List output 


?AUXO 


Auxiliary output 


7AUXI 


Auxiliary input 


?HOME 


Home disk drive 


?SLDSK 


Select disk drive 


7STTRK 


Set tcack 


JSTSEC 


Set sector 


7STDMA 


Set DMA address 


7READ 


Head record 


7WRITE 


Write record 


7LISTS 


List status 


?SCTim 


Translate sector 


7CONOS 


Console output status 


7AKXIS 


Auxiliary input status 


7AUX0S 


Auxiliary output status 


7DVTBL 


Return character device table address 


7DEVIN 


Initialize character device 


7DRTBL 


Return disk drive table address 


7HLTI0 


Set multiple sector count 


PFLUSH 


Plush debloching buffers (not implemented) 


7M0V 


Move memory block 


7TIM 


Signal set or get time from clock 


7BNKSL 


Set bank for further execution 


7STBNK 


Set bank for DMA 


7XM0V 


Set banks for next move 



4.5 BOOT Module 

The BOOT module performs general system initialization, and 
loads and reloads the CCP. Table 4-6 shows the entry points of the 
BOOT module. 



CP/M 3 System Guide 



4.5 BOOT Module 



Table 4-6. BOOT Hodule Entry Points 



The BIOSKRNL module calls ?INIT during 
cold start to perform hardware 
initialization other than character and 
disk I/O. Typically, this hardware can 
include time-of-day clocks, interrupt 
special I/O ports used for 



,ank 



ele. 



BIOSKRNL calls ?LDCCP during cold start to 
load the CCP into the TPA. The CCP can be 
loaded either from the system tracks of 
the boot device or from a file, at the 
discretion of the system implementor . In 
a banked system, you can place a copy of 
the CCP in a reserved area of another bank 
to increase the performance of the 7RLCCP 



BIOSKRNL calls ?RLCCP during warm start to 
reload the CCP into the TPA. In a banked 
system, the CCP can be copied from an 
alternate bank to eliminate any disk 
access. Otherwise, the CCP should be 
loaded from either the system tracks of 
the boot device or from a file. 



4.6 Chacacter I/O 

The CHARIO module handles all character device interfacing. 
The CHARIO module contains the character device definition table 
8CTBL, the character input routine ?CI, the character output routine 
?C0, the character input status routine ?CIST, the character output 
status routine ?COST, and the character device initialization 
routine 7CINIT. 

The BIOS root module, BIOSKRNL. ASM, handles all character I/O 
redirection. This module determines the appropriate devices to 
perform operations and executes the actual operation by calling 7CI, 
?C0, ?CIST, and ?COST with the proper device number {s|. 



eCTBL is the external name for tl 
in Section 3 of this manual, eCTBL i 
each physical device defined by this B 
by a zero byte after the last entry. 

The first field of the charact 
byte device name. This device nairn 
justified, and padded with ASCII 



ructure CHRTBL describe. 

lins an a-byte entry fo 

The table is terminate 



r device table, gCTBL, is 
should be all upper-case, 
paces (20H) . 



CP/M 3 System Guide 



4.6 Character I/O 



The second field of @CTBL is 1 byte containing bits that 
indicate the type of device and its current mode, as shown in Table 
4-7. 



Table 4-7. Node Bits 



Mode Bits 



0000001 Input device (such as a keyboard) 

DOOOOlO Output device (such as a printer) 

DOOOOll Input/output device (such as a terminal 

or modem) 
DOOOlOO Device has software-selectable baud 

rates 
aooiOOO Device may use XON protocol 

DOIOOOO XON/XOFF protocol enabled 

The third field of ecTBL is 1 byte and contains the cuctent 
baud rate for serial devices. The high-order nibble of this field 
is reserved for future use and should be set to zero. The low-order 
four bits contain the current baud rate as shown in Table 4-8. Many 
systems do not support all of these baud rates. 



Table 4-8. 


Baud Rates for 


Serial Devices 


Decimal 


1 Binary | 


Baud Rate 





0000 


none 


1 


0001 


50 




0010 


75 




0011 


110 




0100 


134.5 


5 


0101 


150 


6 


0110 


300 




0111 


600 


e 


1000 


1200 


9 


1001 


1800 


10 


1010 


2400 


11 


1011 


3600 




1100 


4800 


13 


1101 


7200 




1110 


9600 


15 


1111 


19200 



Table 4-9 shows the entry points to the i 
module. The BIOSKRHL module calls these 
machine-dependent character I/O. 



CP/H 3 System Guide 



1.6 Character I/O 



Table 4-9. Character Device Labels 



Character Device Input 



Character Device Output 

?C0 is called with a device number in register 
B and a character in register C. It should 
wait until the device is ready to accept 
another character and then send the character. 
The character is in 8-bit ASCII with no parity. 



Character Device Input Status 

?CIST is called with a device number in 
register B. It should return with register A 
set to zero if the device specified has no 
input character ready,- and should return with A 
set to OFFH if the device specified has an 
input character ready to be read. 



7COST Character Device Output Status 

?COST is called with a device number in 
register B. It should return with register A 
set to zero if the device specified cannot 
accept a character immediately, and should 
return with A set to OFFH if the device is 
ready to accept a character. 



7CINIT Character Device Initialization 

7CINIT is called for each of the 16 character 
devices, and initializes the devices. Register 
C contains the device number. The 7CINIT 
routine initializes the physical character 
device specified in register C to the baud rate 
contained in the appropriate entry of the 
CHRTBL. You only need to supply this routine 
if I/O redirection has been implemented. It is 
referenced only by the DEVICE utility supplied 
with CP/M 3. 



CP/M 3 System Guide 4.7 disJ; j/q 

4.7 Disk I/O 

The separation of the disk I/O section of the BIOS into several 
modules allows you to support each particular disk controller 
independently from the rest of the system, A manufacturer can 
supply the code for a controller in object module form, and you can 
link it into any existing modular BIOS to function with other 
controllers in the system. 

The data structure called the Extended Disk Parameter Header, 
or XDPH, contains all the necessary information about a disk drive 
BIOSKRNL.ASM locates the XDPH for a particular logical drive using 
the Drive Table. The XDPH contains the addresses of the HEAD, 
WRITE, initialization, and login routines. The XDPH also contains 
the relative unit number of the drive on the controller, the current 
media type, and the Disk Parameter Header (DPH) that the BDOS 
requires. Section 3 of this manual describes the Dish Parameter 
Header. 

The code to read and write from a particular drive is 
independent of the actual CP/M logical drive assignment, and works 
with the relative unit number of the drive on the controller. The 
position of the XDPH entry in the DRVTBL determines the actual CP/M 
3 drive code. 

4.7.1 Disk I/O Structure 

The BIOS requites a DRVTBL module to locate the disk driver. 



The drive table module, DRVTBL, contains the addresses of each 
XDPH defined in the system. Each XDPH referenced in the DRVTBL must 
be declared external to link the table with the actual disk modules. 

The XDPHs are the only public entry points in the disk I/O 
modules. The root module references the XDPHs to locate the actual 
I/O driver code to perform sector READS and WRITES, when the READ 
and WRITE routines ace called, the parameters controlling the READ 
or WRITE operation are contained in a series of global variables 
that are declared public in the root module. 

4.7.2 Drive Table Module (DRVTBL) 

The drive table module, DRVTBL, defines the CP/M absolute drive 
codes associated with the physical disks. 

The DRVTBL module contains one public label, @DTBL. 9DTBL is a 
16-word table containing the addresses of up to IG XDPH's. Each 
XDPH name must be declared external in the DRVTBL. The first entry 
corresponds to drive A, and the last to drive P. You must set an 
entry to if the corresponding drive is undefined. Selecting an 
undefined drive causes a BDOS SELECT error. 



CP/M 3 System Guide 



4.7 Disk I/O 



4.7.3 Extended Disk Paraaeter Headers (XDFHs) 

An Extended Disk Parameter Header (XDPH) consists of a prefix 
and a regular Disk Parameter Header as described in Section 3. The 
label of a XDPH references the start of the DPH. The fields of the 
prefix are located at relative offsets from the XDPH label. 

The XDPHs for each unit of a controller are the only entry 
points in a particular disk drive module. They contain both the DPH 
Cor the drive and the addresses of the various action routines for 
that drive, including READ, WRITE, and initialization. Figure 4-1 
shows the format of the Extended Disk Parameter Header. 



ADDRESS 


LOW BYTE 



HIGH BYTE 
78 15 


XDPH-10 


addrol sector WRITE 


XDPH-8 


add. of secior nEAD 


XDPH-6 


addr of drive LOGIN 


XDPH-4 


addr of drive INIT 


XDPH-2 


unil 1 type 


XDPH'O 




add 


Of franslate fable 


XDPHi^2 








XDPH-4 








XDPH-6 








XDPH-B 








XDPH-IO 


Med 


a Flag 







XDPH-12 


addr of DPB 


XDPH-14 


addr of CSV 


XDPH-16 


addr of ALU 


XDPH-18 


addr of DIRBCB 


XDPH-20 


addr ol DTABCB 


XDPH+Z2 


addr of HASH 


XDPH -24 


.as. bar,K | 



Figure 4-1. XDPH Fom 



CP/M 3 System Guide 



4.7 Disk I/O 



Table 4-10 describes the fields of each Extended Disk Parameter 



Table 4-10. Fields of Bach XDPH 



Field 


1 Meaning 


WRITE 


The WRITE word contains the address of the 
sector WRITE routine for the drive. 


READ 


The READ word contains the address of the 
sector READ routine for the drive. 


LOGIN 


The LOGIN word contains the address of the 
LOGIN routine for the drive. 


INIT 


The IHIT word contains the address of the 
fiEst-time initialization code for the 
drive. 


UNIT 


The UNIT byte contains the drive code 
relative to the disk controller. This is 
the value placed in @RDRV prior to calling 
the READ, WRITE, and LOGIN entry points of 
the drive. 


TYPE 


The TYPE byte is unused by the BIOS root, 
and is reserved for the driver to keep the 
current density or media type to support 
multiple-format disk subsystems. 


regular DPH The remaining fields of the XDPH comprise 
a standard DPH, as discussed in Section 3 
of this manual. 



4.7.4 



Subroutine Entry Points 

The pointers contained : 



. the XDPH 

declared public. Only the XDPH itself 
references the XDPHs only through th 
BIOS subroutine entry points. 



f is public. 
@DTBL. Table 



he actual code 

The BIOS root 
4-11 shows the 



CP/M 3 System Guii 



Table 4-11. Subroutine Entry Points 

it Meaning 

When the WRITE routine is called, the 
address of the XDPH is passed in registers 
DE . The parameters for the WRITE 
operation are contained in the public 
variables MDBV, gRDBV, @TRK, eSECT, 9DMA, 
and @DBNK . The WRITE routine should 
return an error code in register A. The 
code 00 means a successful operation, 01 
means a permanent error occurred, and 02 
means the drive is write-protected if that 
feature is supported. 

When the READ routine is called, the 
address of the XDPH is contained in 
registers DE. The parameters for the READ 
operation are contained in the public 
variables @ADRV, @RDEV, gTRK, @SECT, SDMR, 
and eOBNK. The READ routine should return 
an error code in register A. A code of 00 
means a successful operation and 01 means 
a permanent error occurred. 



lalled before the 
e, and allows the 
of density. The 



The LOGIN routine is 
BDOS logs into the dr: 
automatic determinatit 
LOGIN routine can alter the various 
parameters in the DPH , including the 
translate table address (TRANS) and the 
Disk Parameter Block (DPBJ. The LOGIN 
routine can also set the TYPE byte. On 
single media type systems , the LOGIN 
routine can simply return. When LOGIN is 
called, the registers DE point to the XDPH 
for this drive. 

The BOOT entry of the BIOSKRNL module 
calls each INIT routine during cold start 
and prior to any other disk accesses. 
INIT can perform any necessary hardware 
initialization, such as setting up the 
controller and interrupt vectors, if any. 



{ 1 

n 



4.7.5 



Erri 



: Handling and Recovery 



The HEAD and WRITE routines should perform several retries of 
an operation that produces an error. If the error is related to a 
seek operation or a record not found condition, the retry routine 
can home or restore the drive, and then seek the correct track. The 
exact sequence of events is hardware-dependent. 



p. CP/M 3 System Guide 4-7 Disk I/O 

When a nonrecoverable error occurs, the READ or WRITE routines 

can print an error message informing the operator of the details of 

"" the error. The BIOSKRNL module supplies a subroutine, ?PDERR, to 

print a standard BIOS error message header. This routine prints the 

following message: 

— . BIOS Err on D: T-nn S-nn 

The D: is the selected drive, and T-nn and S-nn display the track 
and sector number for the operation. The READ and WRITE routines 
should print the exact cause of the error after this message, such 
"~ " ■ Ready, or Write Protect. The driver can then ask the 
''""■' " J desired, and return an error code 

However, if the @ERMDE byte In the System Control Block 
Indicates the BDOS is returning error codes to the application 
program without printing error messages, the BIOS should simply 
return an error without any message. 

4.7.6 Multiple Sector I/O 

The root module global variable ecNT contains the multisector 
count. Refer to Sections 2.5 and 3.4.3 for a discussion of the 
considerations regarding multirecord I/O. 

4.8 MOVE Module 

The MOVE Module performs memory-to-memory block moves and 
controls bank selection. The ?MOVE and 7XM0VE entry points 
correspond directly to the MOVE and XMOVE jump vector routines 
documented in Section 3. Table 4-12 shows the entry points for the 
HOVE module. 



CP/M 3 Sytem Guide 



MOVE Module p. 



Table 4-12. Hove Module Entry Points 



?MOVE Memory- to -memory i 



7M0VE is called with the source address for 
the move in register DB , the destination 
address in register HL, and the byte count in 
register BC. If ?XMOVE has been called since 
the last call to 7M0VB, an interbank move must 
be performed. On return, registers HL and DE 
must point to the next bytes after the MOVE, 
This routine can use special DMA hardware for 
the interbank move capability, and can use the 
Z90 LDIR instruction for intrabank moves. 



7XM0VE Set banks for one following 7M0VE 



?XHOVE is called with the destination bank in 
register B and the source bank in register C, 
Interbank moves are only invoked if the DPHs 
specify deblocking buffers in alternate banks, 
7 XMOVE only appl ies to one call to 7M0VE . 
(Not implemented in the example.) 



?BAH!C Set bank for executii 



7BRKK is called with the bank address in 
register A. This bank address has already 
been stored in @CBNK for future reference. 
All registers except A must be maintained upon 



4.9 Linking Modules into the BIOS 

The following lines are examples of typical link commands to 
build a modular BIOS ready for system generation with GEKCPM: 

LINK BNKBI0S3[bl=BNKBI0S,SCB, BOOT, CHARIO, MOVE, DRVTBL,<disk_moduleS> 
LINK BIOS 3 [OS] =BIOS,SCB, BOOT, CHARIO rMOVE,DRVTBL,<disk_moduleS> 



End of Section 4 



Section 5 
System Generation 

l^is section describes the use of the GENCPM utility to create 
a memory image CPM3.SYS file containing the elements of the CP/M 3 
operating system. This section also describes customizing the 
LDRBIOS portion of the CPMLDR program, and the operation of CPMLDR 
to read the CPM3.SYS file into memory. Finally, this section 
describes the procedure to follow to boot CP/M 3. 

In the nonbanked system, GENCPM creates the CPM3.SYS file from 
the BD0S3.SPR and your customized BI0S3.SPR files. in the banked 
system, GENCPM creates the CPM3.SYS file from the RESBD0S3.SPR file, 
the BNKBDOS3.SPR file, and your customized BNKBI0S3.SPR file. 

If your BIOS contains a segment that can reside in banked 
memory, GENCPM separates the code and data in BNKBI0S3 SPR into a 
banked portion which resides in Bank just below common memory, and 
a resident portion which resides in common memory. 

GENCPM relocates the system modules, and can allocate Dhvsicai 
record buffers, allocation vectors, checksum vectors, and hash 
tables as requested in the BIOS data structures. It also relocates 
references to the System Control Block, as described on page 27 
GENCPM accepts its command input from a file, GENCPM. DAT or 
interactively from the console. 

5.1 GBHCPM Dtility 
Syntax: 

GENCPM (aOTO I AUTO DISPLAY} 



GENCPM oceates a memory image CPM3.SYS file, containing the 
CP/M 3 BDOS and customized BIOS. The GENCPM utility performs late 
resolution of intermodule references between system modules. GENCPM 
^fiTe"GMCPM^DA^^ '"^'''' interactively from the console or from 



— ^.^w.^. .^ iiic^, ill uiiu uaii^tfu aystem, tjtNuPM 

creates the CPM3.SYS file from the RESBD0S3.SPR, the BNKBD0S3.SPR 
and the BNKBI0S3.SPR files. Remember to back up your CPM3 SYS file 
before executing GENCPM, because GENCPM deletes any existing 
CPH3.SYS file before it generates a new system. 



CP/M 3 System Guide 5.1 The GENCPM Utility f^ 

I I 

Input Files: 

Banked System Nonbanked System . i 

BNKBI0S3.SPR BIOS3.SPB 

RBSBDOS 3 . SPR BDOS 3 . SPR 

BNKBD0S3.SPR p 

Optionally GENCPM.DAT ' ' 

Output File; „ 

CPM3.SYS 1 I 

Optionally GENCPM.DAT 

GENCPM determines the location of the system modules in memory ' ' 
and, optionally, the number of physical record buffers allocated to 
the system. GENCPM can specify the location of hash tables ^ 
requested by the Disk Parameter Headers (DPHs) in the BIOS. GENCPM i , 
can allocate all required disk buffer space and create all the ) | 
required Buffer Control Blocks (BCBs) . GENCPM can also create 
checksum vectors and allocation vectors. 

GENCPM can get its input from a file GENCPM.DAT. The values in f | 
the file replace the default values of GENCPM. If you enter the ', 
AGTO parameter in the command line GENCPM gets its input from the 
fileGENCPM.DAT and generates a new system displaying only its sign- ^ 
on and aign-of f messages on the console. If ADTO is specified and a . | 
GENCPM.DAT file does not exist on the current drive, GENCPM reverts 
to manual generation. 

If you enter the AUTO DISPLAY parameter in the command line, r^ 

GENCPM automatically generates a new system and displays all I ; 
questions on the console. If AUTO DISPLAY is specified and a 
GENCPM.DAT file does not exist on the current drive, GENCPM reverts 

to manual generation. If GENCPM is running In AUTO mode and an „ 

error occurs, it reverts to manual generation and starts from the | . 

beginning. I I 

The GENCPM.DAT file is an ASCII file of variable names and 

their associated values. In the* following discussion, a variable ^« 

name in the GENCPM.DAT file is referred to as a Question Variable. ' I 

A line in the GENCPM.DAT file takes the following general form: '_ 

Question Variable = value | ? | ?value <CR><LP> i ; 

value <* fdecimal value 

or hexadecimal value 

or drive letter (A - P) ^ 

or Yes, No, Y, or N I I 



CP/M 3 System Guide 5.1 The GENCPM Utility 

You can specify a default value by following a question mark 
with the appropriate value, for example ?A or ?25 or ?Y. The 
question mack tells GENCPM to stop and prompt the user for input, 
then continue automatically. At a ?value entry, GENCPM displays the 
default value and stops for verification. 

The following pages display GENCPM questions. The items in 
parentheses are the default values. The Question Variable 
associated with the question is shown below the explanation of the 
answers to the questions. 

Program Questions: 

Use GENCPM.DAT for defaults (Y) ? 

alues from the file 

Enter N - GENCPM uses the built-in default values. 

No Question Variable is associated with this question 

Create a new GENCPM.DAT file (N) ? 

Enter N ~ GENCPM does not create a new GENCPM.DAT fil. 

Enter Y - After GENCPM generates the new CPH3.syS file it 
creates a new GENCPM.DAT file containing the default 
values. 

Question Variable: CRDATAF 

Display Load Table at Cold Boot (Y) ? 

Enter Y - On Cold Boot the system displays the load table 
containing the filename, filetype, hex starting address, 
length of system modules, and the TPA size. 

Enter N - System displays only the TPA size on cold boot. 

Question Variable: PRTMSG 

Number of console columns (#60) ? 

e) for your 

character in the last column must not force a new line 
: console editing in CP/M 3. If your terminal forces a 
r line automatically, decrement the column count by one. 



CP/M 3 System Guide 5.1 The GENCPH Utility 

Number of lines per console page (|24) ? 

Enter the nuinber of the lines per screen for your console. 

Question Variable: PAGLEN 
Backspace echoes erased character (N) ? 

) back one column and 



forward one column and displays 



Question Variable: BACKSPC 
Rubout echoes erased character (Y) ? 



Enter N - Rubout moves back one column and erases the 
previous character. 

Question Variable: RUBOUT 
Initial default drive (A:) 7 

Enter the drive code the prompt is to display at cold boot. 

Question Variable; BOOTDRV 
Top page of memory (PP) ? 



Question Variable: MEMTOP 
Bank-switched memory (Y) ? 

Enter Y - GENCPM uses the banked system files. 

Enter N - GENCPM uses the nonbanked system files. 

Question Variable: BNKSWT 

Common memory base page (CO) 7 

This question is displayed only if you answered Y to the 
previous question. Enter the page address of the start of 
1 memory. 



CP/M 3 System Guide 5.1 The GENCPM Utility 

Long error messages (Y) 7 

This question is displayed only if you answered Y to bank- 
switched memory. 

Enter Y - CP/M 3 error messages contain the BDOS function 
number and the name of the file on which the operation was 
attempted. 

: messages do not display the function 

Question Variable: LERROR 

allocation vectors (Y) ? 

This question is displayed only if you answered N to bank- 
switched memory. For more information about double 
allocation vectors, see the definition of the Disk 
Parameter Header ALV field in Section 3. 

creates double-bit allocation vectors for 

ireates single-bit allocation vectors for 

Question Variable: DBLALV 

Accept new system definition (Y) ? 

Enter Y - GENCPM proceeds to the next set of questions. 

Enter N - GENCPM repeats the previous questions and 
displays your previous input in the default parentheses. 
You can modify your answers. 

No Question Variable is associated with this question. 
Number of memory segments (#3) 7 

; question if you answered Y to bank- 
Enter the number of memory segments in the system. Do not 
count common memory or memory in Bank 1, the TPA bank, as a 
memory segment. A maximum of 16 (0 - 15) memory segments 
are allowed. The memory segments define to GENCPM the 
memory available for buffer and hash table allocation. Do 
not include the part of Bank that is reserved for the 
operating system. 

Question Variable: HUHSEGS 



CP/M 3 System Guide 5.1 The GENCPM Utility 

CP/M 3 Base, size, bank (SE, 32,00) 

Enter memory segment table : 
Base , 9 ize , bank ( 00 , BE , ) ? 
Base, size, bank (00,C0,02) 7 
Base, size, bank (00, CO, 03) 7 

Enter the base page, the length, and the bank of the memory 
segment. 

Question Variable: MEMSEGOI where # = to P hex 

Accept new memory segment table entries (Y) ? 

Enter f - GENCPM displays the next group of questions. 

Enter N - GENCPM displays the memory segment table 
definition questions again. 

No Question Variable is associated with this question. 

Setting up dicectocy hash tables: 

Enable hashing for drive d: (Y) : 

GENCPM displays this question if there is a Drive Table and 
if the DPHs for a given drive have an OFFFEH in the hash 
table address Eieid o£ the DPS. The question is asked foe 
every drive d: defined in the BIOS. 

Enter Y - Space is allocated for the Hash Table. The 
address and bank of the Hash Table is entered into the DPH. 

Enter N - No space is allocated for a Hash Table for that 
drive. 

Question Variable: HASHDRVd where d = drives A-P. 

Betting up Blocking/Deblocking buffers: 



of directory buffers for drive ds (ID ? 10 

This question appears only if you are generating a banked 
system. Enter the number of directory buffers to allocate 
for the specified drive. In a banked system, directory 
buffers are allocated only inside Bank 0. In a nonbanked 
system, one directory buffer is allocated above the BIOS. 

Question Variable: NDIRRECd where d - drives A-P. 



CP/M 3 System Guide 5.1 The GENCPM Utility 

Numbec of data buffers for drive d: (tl) 7 1 

This question appears only if you are generating a Banked 
system. Enter the number of data buffers to allocate for 
the specified drive. In a banked system, data buffers can 
only be allocated outside Bank 1, and in common. You can 
only allocate data buffers in alternate banks if your BIOS 
supports interbank moves. In a nonbanked system, data 
buffers are allocated above the BIOS. 

Question Variable: HDTARECd where d = drives A-p. 

Share bufferfs) with which drive {h:) ? 

This question appears only if you answered zero to either 
of the above questions. Enter the drive letter (A-p) of 
the drive with which you want this drive to share a buffer. 



Allocate buffers outside of Coimnom (N) ? 

This question appears if the BIOS XMOVE rout 
implemented. 

utside of 

Answer N - GENCPM allocates data buffers in common. 

Question Variable: ALTBNKSd where d = drives A-P. 

Overlay Directory buffer for drive d: {¥) ? 

This question appears only if you are generating a 
nonbanked system. 

Enter Y - this drive shares a directory buffer with another 
drive. 

al directory buffer 
Question Variable: OVLYDiRd where d = drives A-p. 



CP/M 3 System Guide 5.1 The GENCPM Utility 

Overlay Data buffer for drive d: (Y) ? 

This question appears only if you are generating a 
nontianked system. 

Enter Y - this drive shares a data buffer with another 
drive. 

al data buffer above 



Accept new buffer definitions (Y) 7 

Enter Y - GENCPM creates the CPM3.SYS file and terminates. 

Enter N - GENCPM redisplays all of the buffer definition 
questions. 

No Question Variable is associated with this question. 

Examples: 

The following section contains examples of two system 
generation sessions. If no entry follows a program question, assume 
RETURN was entered to select the default value in parentheses. 
Entries different from the default appear after the question mark. 

EXAMPLE OF CONTENTS OP GENCPM. DAT PILE 

conibas ■■ cO <CH> 

lerroe = ? <CR> 
numsegs = 3 <CR> 

memsegOO = 00,80,00 <CR> 

memsegOl = 0d,b3,02 <CR> 

memsegOf = ?00,cO,10 <CR> 

hashdrva = y <CR> 

hashdrvd = n <CR> 

ndirceca = 20 <CR> 

ndtarecf = 10 <CR> 

EXAMPLE OF SYSTEM GENERATION WITH BANKED MEMORY 
A>GKHCPH 



ult base is Hex, precede entry with # for decimal 



CP/M 3 System Guide 



5.1 The GENCPM Utility 



Use GEHCPM.DAT foc defaults (Y) ? 

Create a new GBNCPM.DAT file (N) ? 

Display Load Map at Cold Boot (Y) 7 

Number of console columns (#80) ? 
Number of lines in console page {*24) ? 
Backspace echoes erased character (N) ? 
Rubout echoes erased character (N) ? 



Top page of memory (FF) 7 
Bank switched memory (Y) ? 
Common memory base page (CO) ? 



Long er 


ror 


messages (Y) 7 


Accept 


lew 


system de£i 


nition (Y) 7 


Setting 


up 


Allocation 


vector for drive 


Setting 


up 


Checksum ve 


ctor for drive A 


Setting 


up 


Allocation 


vector for drive 


Setting 


<^P 


Checksum ve 


ctor for drive B 


Setting 


up 


Allocation 


vector for drive 


Setting 


up 


Checksum ve 


ctoc for drive C 


Setting 


up 


Allocation 


vector for drive 


Setting 


up 


Checksum ve 


ctor for drive D 


••• Ban 


1 


and Common 


are not included 


*** in the 


memory segm 


ent table. 



Number of memory segments (#3) ? 

CP/M 3 Base, size, bank (8B,35,00) 

Enter memory segment table: 
Base, size, bank (00,8B,00) ? 
Base, size, bank {0D,B3,02) 7 
Base, size, bank (00, CO, 03) 7 

CP/M 3 Sys 8BO0H 3500H Bank 00 

Memseg No. 00 OOOOH 8B00H Bank 00 

Memseg No. 01 ODOOH B30DH Bank 02 

Memseg No. 02 OOOOH COOOH Bank 03 






iry segment table entries (Y) 7 



Setting up directory hash tables: 
Enable hashing for drive A: {Y} 7 
Enable hashing for drive B: (Y) 7 
Enable hashing for drive C: (Y) 7 
Enable hashing for drive D: (Y) 7 



CP/M 3 System Guide 5.1 The GENCPM Utility f] 

Setting up Blocking/Deblocking buffers: ^ 

The physical recoid size is 0200H: 

Available space in 256 byte pages: ^ 

TPA = O0P4H, Bank = 009BH, Other banks = 0166H i i 

Number of directory buffers for drive A: (#32) 7 



Number of data buffets foe drive A: (#2) ' 
Allocate buffers outside of Common (N) ? 



banks « 0166H 
of directory buffets for drive B: (#32) 



Number of data buffers for arive B: (10) ? 
Share buffer (s) with which drive (A:) 7 

The physical record size is 0080H: 

te oaqes: 

■■ 0166H 

of directory buffers foe drive C: (110) 



Humbet of directory buffers foe drive D: (#0) 7 
Share buffer(s) with which drive (C:) 7 



Accept new buffer definitions (Y) 7 



RESBDOS3 SPR FOOOH OeOOH 
BNKBD0S3 SPB 8700H 2A00H 

*** CP/M 3.0 SYSTEM GENERATICM DONE *** 

In the preceding example GENCPM displays the resident portion of 
BNKBIOSS.SFR first, followed by the banked portion. 



CP/M 3 System Guide 5.1 The GENCPM Utility 

EXAMPLE OF SYSTEM GENERATION WITH NONBANKED MEMORY 

A>GENCPH 

System Generation 

Digital Research 

1 Hex 

Use GENCPM.DAT for defaults (Y) ? 

Create a new GENCPM.DAT file (N) ? 

Display Load Map at Cold Boot (Y) ? 

Number of console columns (#80) ? 
Number of lines in console page (#24) 
Backspace echoes erased character (N) 
Rubout echoes erased character (N) ? 

Initial default drive (A:) ? 



Double allocation vectors (Y) ? 
Accept new system definition (Y) 7 
Setting up Blocking/Deblocking buffers: 
The physical record size is 0200H: 



Overlay Data buffer for drive A: 
, 256 byte pages: 



256 byte pages 



CP/M 3 System Guide 5.1 The GENCPM Utility 



Overlay Directory buffer for drive C: (X) ? 
Share buffer(s) with which drive (A:) ? 



Overlay Directory buffer for drive Ds (Y) 7 
Share buffer(B) with which drive (C:) ? 

256 byte pages: 



Accept new buffer definitit 



■ CP/M 3.0 SYSTEM GENERATION DONE ' 



5.2 Custonizing the CPHUir 

The CPMLDR resides on the system tracks of a CP/M 3 system 
disk, and loads the CPM3.SYS file into memory to cold start the 
system. CPMLDR contains the LDHBDOS supplied by Digital Research, 
and must contain your customized LDRBIOS. 

The system tracks for CP/M 3 contain the customized Cold Start 
Loader, CPMLDR with the customized LDBBIOS, and possibly the CCP. 

The COPYSYS utility places the Cold Start Loader, the CPMLDS, 
and optionally the CCP on the system tracks, as shown in Table 5-1. 



m CP/M 3 System Guide 



5.2 Customizing the CPMLDR 



Table 5-1. Saiiple CP/M 3 SyBtea Tcack Ocganixation 



Track 


-"" 


1 Page 


Memory Add 


ess 


CP/M 3 Module Name 


00 


01 




Boot Address 


Cold Start Loader 


00 


oz 


00 


OlOOH 




CPMLDR 
and 


00 


21 


09 


0A80H 




LDRBDOS 


00 


22 


10 


OBOOH 




LDRBIOS 


00 


26 


12 


ODOOH 






01 


01 


12 


OD80H 






oi 


26 


25 


lAOOH 




CCP 



Typically 
Track 0, Sectot 
depressed. 



he Cold Start Loader is loaded into memory from 
1 of the system tracks when the reset button is 

The Cold Start Loader then loads CPMLDR from the system 

memory. 



Alternatively, if you are 
system, you can run CPMLDR.COM as 
CPMLDR.COM into memory at locat 
CPM3.SXS file from User on dri 

Use the followir 
£ile, including your 



starting from an existing CP/M 2 
a transient program. CP/M 2 loads 
on lOOH. CPMLDB then reads the 
'e A and loads it into memory. 

stomized CPMLDR.COM 



L LDRBIOS. ASM file. 



J LDRBIOS, REL 



3) Link the supplied CPMLDR. REL file with the LDRBIOS. REL file 
you created to produce a CPMLDR.COM file. 

A>LINK CPIfLDR[L100]=CPIfLDS,LDBBIOS 

Replace the address 100 with the load address to which your 
boot loader loads CPMLDR.COM. You must include a bias of 
lOOH bytes for buffer space when you determine the load 



CP/M 3 System Guide 5.2 Customizing the CPMLDR 

The CPMLDR requires a customized LDRBIOS to perform disk input 
and console output. The LDRBIOS is essentially a nonbanked BIOS. 
The LDRBIOS has the same JMP vector as the regular CP/M 3 BIOS. The 
LDRBIOS is called only to perform disk reads (READ) from one drive, 
console output (CONOtIT) for sign-on messages, and minimal system 
initialization. 

The CPMLDR calls the BOOT entry point at the beginning of the 
LDHBIOS to allow it to perform any necessary hardware 
initialization. The BOOT entry point should return to CPMLDR 
instead of loading and branching to the CCP, as a BIOS normally 
does. Note that interrupts are not disabled when the LDRBIOS BOOT 
routine is called. 

Test your LDRBIOS completely to ensure that it properly 
performs console character output and disk reads. Check that the 
proper tracks and sectors are addressed on all reads and that data 
is transferred to the proper memory locations . 

You should assemble the LDRBIOS. ASM file with a relocatable 
origin of OOOOH. Assemble the LDRBIOS with RMAC to produce a 
LDRBIOS. REL file. Link the LDRBIOS. REL file with the CPMLDR. REL 
file supplied by Digital Research to create a CPMLDR.COM fi" 
the L option in LINK to specify the load o ' '""" ' 

the boot loader on track sector 1 loads 

■ deleted from the LDRBIOS to 
restriction on the length of 
the LDRBIOS! it cannot extend above the base of the banked portion 
of CP/M 3. (GENCPM lists the base address of CP/M 3 in its load 
map.) If you plan to boot CP/M 3 from standard, single-density, 
eight-inch floppy disks, your CPMLDR must not be longer than 19B0H 
to place the CPMLDR.COM file on two system tracks with the boot 
sector. If the CCP resides on the system tracks with the Cold Start 
Loader and CPMLDR, the combined lengths must not exceed 1980H. 

5.3 CPMLDR Utility 
Syntax: 



CPMLDR loads the CP/M 3 system file CPM3.SYS into Bank and 
transfers control to the BOOT routine in the customized BIOS. You 
can specify in GENCPM for CPMLDR to display a load table containing 
the names and addresses of the system modules. 

The CPM3.SYS file contains the CP/M 3 BDOS and customized BIOS. 
The file CPM3.SYS must be on drive A in USER 0. You can execute 
CPMLDR under SID™ or DDT™ to help debug the BIOS. A $B in the 
default File Control Block (FCB) causes CPMLDR to execute a RST 7 
{SID breakpoint) just before jumping to the CP/M 3 Cold Boot BIOS 
entry point. 



CP/M 3 System Guide 5.3 CPMLDH Utili! 

Input File; 

CPM3.SYS 



A>CFHLDR 

CP/M V3.0 Loader 

Copyright (C) 1982, Digital Research 

BNKBI0S3 SPR F600H OAOOH 

BNKBI0S3 SPR BBOOH 0500H 

RESBD0S3 SPR FIOOH OSOOH 

BMKBDOS3 SPR 9A00H 2100H 



In the preceding example, CPMLDR displays its name and version 
number, the Digital Research copyright message, and a four-column 
load table containing the filename, filetype, hex starting address, 
and length of the system modules. CPMLDR completes its sign-on 
message by indicating the size of the Transient Program Area (TPA) 
in kilobytes. The CCP then displays the system prompt, A> . 

5.4 Booting CP/M 3 

The CP/M 3 cold start operation loads the CCP, BDOS, and BIOS 
modules into their proper locations in memory and passes control to 
the cold start entry point (BIOS Function 0: BOOT) in the BIOS. 
Typically, a PROM-based loader initiates a cold start by loading 
sector on track 1 of the system tracks into memory and jumping to 
It. This first sector contains the Cold Start Loader. The Cold 
Start Loader loads the CPMLDR. COM program into memory and jumps to 
it. CPMLDR loads the CPM3.SYS file into memory and jumps to the 
BIOS cold start entry point. 



CP/M 3 System Guide 5.4 Booting CP/M 3 



To boot the CP/M 3 system, use the following procedure: 

1) Create the CPM3.SYS file. 

2) Copy the CPM3.SYS file to the boot drive. 

3) Create a CPMLDH.COM for your machine. 

4) Place the CPMLDR.COM file on your system tracks using SYSGEN 
with CP/M 2 or COPYSYS with CP/M 3. The boot loader must 
place the CPMLDB.COM file at the address at which it 
originated. If CPMLDR has been linked to load at lOOH, you 
car run CPMLDR under CP/M 2. 

The COPYSYS utility handles initialization of the system 
tracks. The source of COPYSYS is included with the standard CP/M 3 
system because you need to customize COPYSYS to support nonstandard 
system disk formats. COPYSYS copies the Cold Start Loader, the 
CPMLDR.COM file, and optionally the CCP to the system tracks. Refer 
to the COPYSYS. ASM source file on the distribution disk. 

End of Section 5 



Section 6 
Debugging tine BIOS 



This section describes a sample debugging session for a 
nonbanked CP/M 3 BIOS. You must create and debug your nonbanked 
system first, then bring up the banked system. Note that your 
system probably displays addresses that differ from the addresses in 
the following example. 

You can use SID, Digital Research's Symbolic Debugger Program, 
running under CP/M 2.2, to help debug your customized BIOS. The 
following steps outline a sample debugging session. 

1) Determine the amount of memory available to CP/M 3 when the 
debugger and CP/M 2.2 are in memory. To do this, load the 
debugger under CP/M 2.2 and list the jump instruction at 
location 0005H. In the following example of a 64K system, 
C500 is the base address of the debugger, and also the 
maximum top of memory that you can specify in GENCPM for 
your customized CP/M 3; system. 

A>SID 

CP/M 3 SID - Version 3.0 

#1.5 

0005 JMP C500 



2) Running under CP/M 2.2, use GENCPM to generate a CPM3.SYS 
file, which specifies a top of memory that is less than the 
base address of the debugger, as determined by the previous 
step. Allow at least 256K bytes for a patch area. In this 
example, you can specify C3 to GENCPM as the top of memory 
for your CP/M 3 system. 



Top page of memory (PF)? C3 



3) Now you have created a system small enough to debug under 
SID. Use SID to load the CFMLDR.COM file, as shown in the 



CP/M 3 System Guide 6 Debugging the BIOS n 

following examples 



A>SID CPHLDR.COH 

CP/M 3 SID - Version 
NEXT MSZE PC END 
0E80 0E80 0100 D4FF 



and the following 



CP/M V3.0 LOADER 

Copyright (c) 1982, Digital Research 



34K TPA 
* 01A9 



6) With the CP/M 3 system in the proper location, you can set 
passpoints in your BIOS. Use the L command with the 
address specified as the beginning of the BIOS by the 
CPMLDR load table as shown in step 5 above. This L command 
causes SID to display the BIOS jump vector which begins at 
that address. The jump vector indicates the beginning 
address of each subroutine in the table. For example, the 
first jump instruction in the example below is to the Cold 
Boot subroutine. 

IIAAOO 



n 
n 



4) Use the I command in SID, as shown in the next example, to _ 
place the characters 5B into locations 005DH and 005EH of \ 
the default FCB based at 005CH. The SB causes CPMLDR.COM | ' 
to break after loading the CPM3.SYS file Into memory. 

USB p 

5) Transfer control to CPMLDR using the G command: 



n 



CP/M 3 System Guide 6 Debugging the BIOS 

The output from your BIOS might look like this: 

JMP AA58 
JMP AABE 
JMP ABA4 
JHP ABAF 
JHP ABCA 



the Cold BOOT routine. Use the P 
to set a passpoint at that address. 



8) Continue vith the CPHL0R.COM program by entering the G 
command, followed by the address of Cold Boot, the first 
entry in the BIOS jump vector. 



9) In response to the G command, the CPMLDR transfers control 
to the CP/M 3 operating system. If you set a passpoint in 
the Cold BOOT routine, Che program stops executing, control 
transfers to SID, and you can begin tracing the BOOT 
routine. 

10) When you know the BOOT routine is functioning correctly, 
enter passpoints for the other routines you want to trace, 
and begin tracing step by step to determine the location of 
problems. 



:ies Guide for the CP/M 
Hussion of all the SID 



End of Secti< 



Appendix A 
Removable Media Considerations 



All disk drives under CP/M 3 are classified as either permanent 
or removable. In general, removable drives support media changea; 
permanent drives do not. Setting the high-order bit in the CKS 
field in a drive's Disk Parameter Block (DPB) marks the drive as a 
permanent drive. 

The BDOS file system distinguishes between permanent and 
removable drives. If a drive is permanent, the BDOS always accepts 
the contents of physical record buffers as valid. In addition, it 
also accepts the results of hash table searches on the drive. 

On removable drives, the status of physical record buffers is 
more complicated. Because of the potential for media change, the 
BDOS must discard directory buffers before performing most directory 
related SDOS function calls. This is required because the BDOS 
detects media changes by reading directory records. When it reads a 
directory record, the BDOS computes a checksum for the record, and 
compares the checksum to the currently stored value in the drive's 
checksum vector, if the checksum values do not match, the BDOS 
assumes the media has changed. Thus, the BDOS can only detect a 
media change by an actual directory READ operation. 

A similar situation occurs with directory hashing on removable 
drives. Because the directory hash table is a memory-resident 
table, the BDOS must verify all unsuccessful hash table searches on 
removable drives by accessing the directory. 

The net result of these actions is that there is a significant 
performance penalty associated with removable drives as compared to 
permanent drives. In addition, the protection provided by 
classifying a drive as removable is not total. Media changes are 
only detected during directory operations. If the media is changed 
on a drive during BDOS WRITE operations, the new disk can be 
damaged . 

The BIOS media flag facility gives you another option for 
supporting drives with removable media. However, to use this 
option, the disk controller must be capable of generating an 
interrupt when the drive door is opened. If your hardware provides 
this support, you can improve the handling of removable media by 
implementing the following procedure: 



) Ma 


rk the drive as a permanent drive and 


set the DPB CKS 


pa 


ameter to the total number of directory 


ntries, divided 


by 


four. For example, set the CKS field fo 


a disk with 96 


di 


ectory entries to 8018H. 





n 

CP/M 3 System Guide A Removable Media Considerations ^ 

J ■ 
2) Implement an interrupt service routine that sets the 9MEDIA 

flag in the System Control Block and the DPH MEDIA byte for „ 

the drive that signaled the door open condition. | ' 

By using the media flag facility, you gain the performance 
advantage associated with permanent drives on drives that support p 

removable media. The BDOS checks the System Control Block @MEDIA | I 

flag on entry for all disk-related function calls. If the flag has 
not been set, it implies that no disks on the system have been 
changed. If the flag is set, the BDOS checks the DPH MEDIA flag of ^ 

each currently logged-in disk. If Che DPH MEDIA flag of a drive is i j 

set, the BDOS reads the entire directory on the drive to determine ' 

whether the drive has had a media change before performing any other 
operations on the drive. In addition, it temporarily classifies any 
permanent disk with the DPH MEDIA flag set as a removable drive. " 

Thus, the BDOS discards all directory physical record buffers when a 
drive door is opened to force all directory READ operations to 
access the disk. 

To summarize, using the BIOS MEDIA flag with removable drives i ■ 

offers two important benefits. First, because a removable drive can I _ 
be classified as permanent, performance is enhanced. Second, 
because the BDOS immediately checks the entire directory before 

performing any disk-related function on the drive if the drive's DPH jT 

MEDIA flag is set, disk integrity Is enhanced. I , 

End of Appendix A ^ 



Appendix B 
Auto-density Support 



Auto-density support teEecs to the capability of CP/M 3 to 
support different types of media on a single drive. For example, 
some floppy-disk drives accept single-sided and double-sided disks 
in both single-density and double-density formats . Auto-density 
support requires that the BIOS be able to determine the current 
density when SELDSK is called and to subsequently be able to detect 
a change in disk format when the READ or WRITE routines are called. 

To support multiple disk formats, the drive's BIOS driver must 
include a Disk Parameter Block (DPB) for each type of disk or 
include code to generate the proper DPB parameters dynamically. In 
addition, the BIOS driver must determine the proper format of the 
disk when the SELDSK entry point is called with register E bit 
equal to (initial SELDSK calls). If the BIOS driver cannot 
determine the format, it can return OOOOH in register pair HL to 
indicate the select was not successful. Otherwise, it must update 
the Disk Parameter Header (DPH) to address a DPB that describes the 
current media, and return the address of the DPH to the BDOS. 

Note: all subsequent SELDSK calls with register E bit equal to 1, 
the BIOS driver must continue to return the address of the DPH 
returned in the initial SELDSK call. The value OOOOH is only a 
legal return value for initial SELDSK calls. 

After a driver's SELDSK routine has determined the format of a 
disk , the driver 's READ and WRITE routines assume this is the 
correct format until an error is detected. If an error is detected 
and the driver determines that the media has been changed to another 
format, it must return the value OFFH in register A and set the 
media flag in the System Control Block. This signals the BDOS that 
the media has changed and the next BIOS call to the drive will be an 
initial SELDSK call. Do not modify the drive's DPH or DPB until the 
initial SELDSK call is made. Note that the BDOS can detect a change 
in media and will make an initial SELDSK call, even though the BIOS 
READ and WRITE routines have not detected a disk format change. 
However, the SELDSK routine must always determine the format on 
initial calls. 

A drive's Disk Parameter Header (DPH) has associated with it 
several uninitialized data areas: the allocation vector, the 
checksum vector, the directory hash table, and physical record 
buffers. The size of these areas is determined by DPB parameters. 
If space for these areas is explicitly allocated in the BIOS, the 
DPB that requires the most space determines the amount of memory to 
allocate. If the BIOS defers the allocation of these areas to 
GENCPM, the DPH must be initialized to the DPB with the largest 
space requirements. If one DPB is not largest in all of the above 
categories, a false one must be constructed so that GENCPM allocates 
sufficient space for each data area. 

End of Appendix B 



Appendix C 
Modifying a CP/M 2 BIOS 



If you are modifying ■ 
the following changes. 



1 existing CP/M 2.2 BIOS, yoti i 



• mie BIOS jump vector is expanded from 17 ei 
2.2 to 33 entry points in CP/M 3. You ; 
necessary additional routines. 

• The Disk Paran 



meter Block data 



See Section 3 of this manual, "CP/M 3 BIOS Functional 
Specifications, " for details of the BIOS data structures and 
subroutines. The following table shows all CP/H 3 BIOS functions 
with the changes necessary to support CP/M 3. 



Table C-1. CP/K 3 BIOS Functions 



Function 


Meaning 


BIOS Function 


00 ! BOOT 




The address for the JMP at location 5 must 
be obtained frcm gMXTPA in the System 
Control Block. 


BIOS Function 


01 ! WBOOT 




The address for the JMP at location 5 must 
be obtained from eMXTPA in the System 
Control Block. The CCP can be reloaded 
frran a file. 


BIOS Function 


02: CONST 




Can be implemented unchanged. 


BIOS Function 


03: CONIN 




Can be implemented unchanged. Do not mask 
the high-order bit. 



CP/M 3 System Guide 



C Modifying a CP/M 2 BIOS 



Table C-1. (continued) 



Function 


Meaning 


BIOS Functio 


n 04: CONOUT 




Can be implemented unchanged. 


BIOS Functio 


n 05: LIST 




Can be implemented unchanged, 


BIOS Functio 


n 06: AUXOUT 




Called PUNCH in CP/M 2. Can be 
implemented unchanged. 


BIOS Functio 


n 07: AUXIN 




Called READEH in CP/M 2. Can be 
implemented unchanged. Do not mask the 
high-ordec bit. 


BIOS Functio 


n 08: HOME 




No change. 


BIOS Functio 


n 09: SELDSK 




Can not return a select error when SELDSK 
is called with bit in register E equal 
to 1. 


BIOS Functio 


n 10: SETTRK 




No change. 


BIOS Functio 


n 11: SETSEC 




Sectors are physical sectors, not logical 
128-byte sectors. 


BIOS Functio 


n 12: SETDMA 




Now called for every BEAD or WRITE 
operation. The DMA buffer can now be 
greater than 128 bytes. 



C Modifying a CP/M 2 BIOS 



Table C-1. [continued) 



Function 




Meaning 


BIOS Fun 


ctio 


n 13: READ 

READ operations are in terms of physical 
sectors. READ can return a OFFH error 
code if it detects that the disk format 
has changed. 


BIOS Fun 


ctio 


n 14: WRITE 

WRITE operations are in terms of physical 
sectors. If write detects that the disk 
is Read-only, it can return error code 2. 
WRITE can return a OFFH error code if it 
detects that the disk format has changed. 


BIOS Fun 


ctio 


n 15: LISTST 

Can be implemented unchanged. 


BIOS Fun 


ctio 


n 16: SECTRN 

Sectors are physical sectors, not logical 
128-byte sectors. 



The followii 
BIOS Functii 
BIOS Functi< 
BIOS Functii 
BIOS Functii 
BIOS Functii 
BIOS Functic 
BIOS Functii 
BIOS Functic 
BIOS Functii 
BIOS Functi< 



I is a list of 

I 17: CONOST 

I 18: AUXIST 

L 19: AUXOST 

I 20: DEVTBL 

, 21: DEVINI 

. 22: DRVTBL 

23: MULTIO 

24: FLUSH 

2 5 : MOVE 

26: TIME 



3 System Gu 


de 




C 


Modifying a CP/M 2 BIOS 


BIOS Functi 


>n 27: 


SELMEM 






BIOS Functi 


Dn 28: 


SETBNK 






BIOS Functi 


an 29: 


XMOVE 






BIOS Functi 


an 30: 


USERF 






BIOS Functi 


on 31: 


RESERVl 






BIOS Functi 


an 32! 


RESERV2 







End of Appendi: 



Appendix D 
CPM3.SYS File Format 





Table 


D-1. 


CPMa.SYS 


File 


Focaat 


Record 




Cont 


>nts 






1 
2 


■> 


Header Recntd 
Print Record 
CP/M 3 operat 
reverse order 


(128 bytes) 
128 bytes) 
ng system in 
top down. 





Table D-2. Header Record Definition 


Byte 


Contents 





Top page plus one, at which the resident 
portion of CP/M 3 is to be loaded top down. 


1 


Length in pages (256 bytes) of the resident 
portion of CP/M 3. 


2 


Top page plus one, at which the banked portion 
of CP/M 3 is to be loaded top down. 


3 


Length in pages (256 bytes) of the banked 
portion of CP/M 3. 


4-5 


Address of CP/M 3 Cold Boot entry point. 


6-15 


Reserved. 


16-51 


Copyright Message. 


52 


Reserved. 


53-58 


Serial Number. 


59-127 


Reserved. 



End of Append i: 



p 
p 



Appendix E 
Root Module of Relocatable BIOS for CP/M 3 



All the listings in Appendixes E through I ace assembled with 
RMAC, the CP/M Relocating Macco RsserabLer, and cross-ceferenced with 
XHEP" , an assembly language cross-eeEerence program used with RMAC, 
These listings ace output ftrom the XREF program. The assembly 
language sources ace on youc distribution disk as .ASM files. 



Listing B-1. Root Module of Relocatable BIOS foe CP/H 3 



CP/M 3 System Guii 



Root Module of Relocatable BIOS 



Listing E-1. (continued) 



CP/M 3 System Guide E Hoot Module of Relocatable BIOS 



Listing E-1. (continued) 



CP/M 3 System Guide E Root Module of Relocatable BIO! 



Listing E-1. (continued) 



CP/M 3 System Guide E Root Module of Relocatable BIOS 



Listing B-1. (continued) 



CP/M 3 System Guide E Roo 



t Module o£ Relocatable BIOS P 



Listing B-1. (continued) 



•— CP/M 3 System Guide E Root Module of Relocatable BIOS 



Listing E— 1. (continued) 



CP/M 3 System Guide E Rcxit Module of Relocatable BIOS 



Listing E-1. (continued) 



CP/M 3 System Guide E Root Module of Relocatable BIOS 



Listing E— 1. (continued) 



CP/M 3 System Guide E Root Module oE Relocatable BIOS 



Listing B-I. (continued) 



CP/M 3 System Gu 



E Root Module of Relocatable BIOS 



Listing B-1. (continued) 

End of Appendix E 



Appendix F 
System Control Block Definition for CP/M 3 BIOS 



The 5CB.ASM module contains the public definitions of the 
various fields in the System Control Block. The BIOS can reference 
the public variables. 



Listing K-1. System Control Block DeCinition for CP/M 3 BIOS 



CP/M 3 System Guide F System Control Block Definition « 



Listing F-1. (continued) 

End of Appendix F 



Appendix G 
Equates for Mode Byte Bit Fields 



Listing G-1. Equates for Mode Byte Fields: HODBBADD.LIB 

End of Appendix G 



Appendix H 
Macro Definitions for CP/M 3 BIOS Data Structures 



I Listing H-1. Macro Definitioos foe CP/H 3 BIOS Data Stcuctuci 



CP/M 3 System Guide 



Macro Definitii 



Listing H-1. (continued) 



CP/M 3 System Guide H Macro Defii 



Listing H-1. (continued) 

End of Appendix H 



Appendix I 
ACS 8000-15 BIOS Modules 



l.l Boot Loader Module toe CP/H 3 

The BOOT. ASM module performs system initialization other than 
character and disk I/O. BOOT loads the CCP for cold starts and 
reloads it for warm starts. Note that the device drivers in the 
Digital Research sample BIOS initialize devices for a polled, and 
not an interrupt-dr iven, environment. 



Listing I-l. Boot Loader Module for CP/M 3 



CP/M 3 System Guide 



l.l Boot Loader Moaule foe CP/H 3 



Listing I-l. (continuea) 



n 
n 



CP/M 3 System Guide I.l Boot Loader Module for CP/M 3 



Listing l-l. (continuea) 



CP/M 3 System Guide 



1.2 Character I/O Handler 



1.2 Character I/O Handlec for Z80 Chip-based System 

The CHARIO.ASM module performs all character device H 

initialization, input, output, and status polling. CHARIO contains | I 

the character device characteristics table. 



Listing 1-2. Chatacter I/O Handler tor Z80 Chip-based Syst. 



„ CP/M 3 System Guide 



1.2 Character I/O Handle. 






Listing 1-2. (continued) 



CP/M 3 System Guide 



1.2 Character I/O Handler 



Listing 1-2. (continued) 



CP/M 3 System Guide 



1.2 Character I/O Handle. 



Listing 1-2. (continued) 



CP/M 3 System Guide 1.3 Drive Table | 

1.3 Drive Table 

The DRVTBL.ASM module points to the data structures for each I ■ 

configured disk drive. The drive table determines which physical ' 
dislt unit is associated with which logical drive. The data 

structure for each disk drive la called an Extended Disk Parameter ^ 

Header (XDPH) . i 



Listing 1-3. Drive Table 



1.4 Z80 raiA Single-density Disk Handler 

The FD1797SD module initializes the disk controllers for the 
disks described in the Disk Parameter Headers and Disk Parameter 
Blocks contained in this module. FD1797SD is written for hardware 
that supports Direct Memory Access (DMA) . 



Listing 1-4. S80 DWV Single-density Disk Handler 



CP/M 3 System Guide 1.4 Z80 DMA Single-density Disk Handle 



Listing 1-4. (continued) 



CP/M 3 System Gi 



;uide 1.4 ZSO DMA Single-density Disk Handlei 



Listing T-4. (continued) 



^^ CP/M 3 System Guide 1.4 2B0 DMA Single-density Disk Handler 



Listing 1-4. (continued) 



CP/M 3 System Guide 1.4 Z80 DMA Single-density Disk Handler 



Listing 1-4. (continued) 



^- CP/M 3 System Guide 1.4 Z80 DMft Single-density Disk Handler 






Listing 1-4. (continued) 



CP/M 3 System Guide 1.4 ZBO DMA Single-density Disk Handler 



Listing 1-4. (continued) 



CF/M 3 System Guide 1.4 Z80 DMA Single-density Disk Handler 



Listin9 1-4. (continued) 



CP/M 3 System Guide 1.4 Z80 DMA Single-density Disk Handler 



Listing 1-4. (continued) 



1.5 Bank and Hove Hoaule for CP/M 3 Linked BIOS 



Listing 1-5. Bank and Hove Hodule for CP/H 3 Linked BIOS 



^ CP/M 3 System Guide 1.5 Bank i Move Module for Linked BIOS 



Listing 1-5. (continued) 



1.6 I/O Port Addresses for 280 Chip-based System: PORTS, LIQ 

This listing is the PORTS. LIB file on youc distribution 
diskette. It contains the poet addresses for the Z80 chip-based 
system with a Western Digital 1797 Floppy Disk Controller. 



Listing 1-6. I/O Port Addresses for Z80 Chip-based Systen 



CP/M 3 System Guide 1-6 I/O Port Addresse; 



tq.1 pStplOlU 
equ pSiplol*: 
<qu pStpiol. 



Listing 1-6. (continued) 



CP/M 3 System Guide 1-7 Sample Submit Pile 

1.7 Sa^ile SulMiit File Eor ASC SOOO-IS SysteH 

Digital Research used this SUBMIT file to build the sample 



Listing 1-7. Sa^le Su^it File fot ASC aOOO-lS Systea 

End of Appendix I 



Appendix | 
Public Entry Points for CP/M 3 Sample BIOS Modules 



Listing J-1. Public Bntcy Points for CP/H 3 Sample BIOS Modules 

End of Appendix J 



Appendix K 
Public Data Items in CP/M 3 Sample BIOS Modules 





Table K-1, Public Data Itens 


Module 


Public 






Name 


Data 


Description 




BIOSRRNL 










gADRV 


Absolute Logical Drive 


Code 




gRDRV 


Relative logical drive 


code (UNIT) 




@TRK 


Track Number 






9SECT 


Sector Address 






@DMA 


DMA Address 






@DBNK 


Bank for Disk I/O 






9CNT 


Multi-sector Count 






eCBNK 


Cutrent CPU Bank 




CHAfilO 










@CTBL 


Character Device Table 




DBVTBL 










SDTBL 


Drive Table 





End of Appendi: 



Appendix L 
CP/M 3 BIOS Function Summary 





Table L-1 


BIOS Function 


Juap Table Suaaacy 


No. 


Function 


Input 


Output 





BOOT 


None 


None 


1 


WBOOT 


None 


None 


2 


CONST 


None 


A=OFFH if ready 
A-OOH if not ready 


3 


CON IN 


None 


A=Con Char 


4 


CONOOT 


C=Con Char 


None 


5 


LIST 


C«Chac 


None 


6 


AUXOUT 


C=Char 


None 


7 


AUXIN 


None 


A=Chac 


B 


HOME 


None 


None 


9 


SELDSK 


C=Drive 0-15 


HL-DPH addr 






E-Init Sel Flag 


HL=OOOH if invalid dr. 


10 


SETTRK 


BC=Track No 


None 


11 


SETS EC 


BC=Sector No 


None 


12 


SETDMA 


BC=.DMA 


None 


13 


READ 


None 


A=OOH if no Err 

A=01H if Non-tecov Ere 

A=OFFH if media changed 


14 


WRITE 


C=Deblk Codes 


A=O0H if no Eff 
A=01H if Phys Err 
A=02H if Dsk is R/0 
A=OFFH if media charged 


15 


LISTST 


None 


A-OOH if not ready 
A=OFFH if ready 


16 


SBCTRN 


BC=Log Sect No 


HL=Phys Sect No 






DE-Trans Tbl Ad 


r 


17 


CONOST 


None 


A«00H if not ready 
A-OPFH if ready 


18 


AUXIST 


None 


A=OOH if not ready 
A=OFPH if ready 


19 


AUXOST 


None 


A=O0H if not ready 
A=OFFH if ready 


20 


DEVTBL 


None 


HL-Chrtbl addr 


21 


DEVINI 


C-Dev No 0-15 


None 


22 


DRVTBL 


None 


HL-Drv Tbl addr 

HL=OFFFFH 

HL=OFPFEH 


23 


MULT 10 


C=Mult Sec Cnt 


None 


24 


FLUSH 


None 


A=O00H if no err 
A=001H if phyg err 
A=002H if disk R/0 


25 


MOVE 


HL=De8t Adr 


HL & DE point to next 






DE-Souroe Adr 


bytes following MOVE 






BC-Count 





CP/M 3 System Guide 



CP/M 3 BIOS Function Summary 



Table L-1. (continued) 



No. 


Function 


Input Output 


26 


TIME 


C=Get/Set Flag None 


27 


SELMEM 


A=Mcin Bank None 


28 


SETBNK 


AaMem Bank None 


29 


XMOVE 


B=Dest Bank None 
C=Source Bank 


30 


USERF 


Reserved for System Implementot 


31 


RESERVl 


Reserved for Future Use 


32 


RESERV2 


Reserved for Future Ose 



End of Append!: 



Index 



$. 115 




5B, 100, 104 




?, 27, 88 




restriction c 




7AUXI, 77 




7A0XIS, 77 




?AUXO, 77 




7AUX0S, 77 




7BAHK, 75 




7BNKSI,, 77 




7BOOT, 77 




7CI, 75, 78, 80 


?CINIT, 73, 75 


80 


7CIST, 75, 78, 


SO 


?CO, 75, 78, 80 


7CONIK, 77 




7CONO, 77 




7C0SDST, 77 




7C0NST, 77 




?COST, 75, 78, 


80 


7DEVIN, 77 




7DRTBI., 77 




?DVTBL, 77 




7PI,DSH, 77 




7H0ME, 77 




7ISIT, 74, 75, 


7B 


JLDCCP, 74, 75 


78 


7LIST, 77 




?LISTS, 77 




7MLTI0, 77 




7M0V, 77 




7M0VE, 75, 85 




7PDEC, 75, 76 




7PDEHR, 75, 76 


85 


7PMSG, 75, 76 




7 READ, 77 




7RLCCP, 75, 78 




7SCTRN, 77 




7SLDSK, 77 




7STBHK, 77 




7STDMA, 77 




7STSEC, 77 




7STTRK, 77 




7TIM, 77 




7TIME, 75 




7WBOOT, 77 




7WRITE, 77 




7XMOV, 77, 85 




7XM0VE, 75 





@ADRV, 75, 76 
SAIVEC, 28, 29 
SAOVEC, 28, 29 
SBFLGS, 28, 30, 31 
@BNKBF, 18, 28, 29 
eCBNK, 75, 76 
eciVEC, 28, 29 
@LNT, 75, 76, 85 
eCOVEC, 28, 29 
@CRDMA, 28, 29 
SICRDSK, 28, 29 
eCTBL, 74, 75, 78 
@DATE, 25, 28, 31 
eDBNK, 75, 76 
@DMA, 75, 76 
eoTBL, 74, 75 
§EHMDE, 28. 30 
gERDSK, 28, 29 
eERJMP, 28, 31, 32 
ePX, 28, 29 
@HOUR, 25, 28, 31 
eLOVEC, 28, 29 
SMEDIA, 28, 30 
@MIN, 25, 28, 31 
@MLTIO, 28, 
?MXTPA, 18, 28, 
ePDERR, 85 
SRDRV, 75, 76 
0BESEL, 28, 2' 
eSEC, 25, 28, 
eSECT, 75, 76 
@TRK, 75, 76 
gUSRCD, 28, 2! 
eVISFO, 28, 2: 



30, 52 



allocat] 



41 
■, 34, 



See also ALV 
ALO and ALI, 43 
ALV, 34, 38 

banked system, 39 

double, 91 

double-bit, 38 

single-bit, 38 
assembler source file, 
bly language 

irogr, 



efer. 
, 117 



aBsignment vector, 74 
AUTO DISPLAY parameter, 8i 
AUTO parameter, 88 
auto-density support, 109 
automatic login feature, ' 
AUXIN, 16, 17 , 19, 50, 56 
AUXIST, 16, 17, 50, 57 
AUXOST, 16, 17, 50, 58 
AUXOUT, 16, 17, 19, 



56 



5, 6 



76 



WIA buffe: 
selection, 78 
switching, 6 
BANK field, 44, 46 

bank number 
current, 24 



selects, 24 









■equii 



1, 7 



banned BIOS 

assembling, 69 

linking, 69 

preparing, 69 
banhed system 

allocation vector, 39 

BANK field, 46 

BCB data structures, 

BDOS and BIOS, 



mory, 5, 34 
with Bank 1 enabled, 6 

Basic Disk Operating System 
See BDOS 

Basic Input Output System 
See BIOS, 

current, 32 
serial devices, 79 



Bros, 1, 2, 1 




calls to BIOS, 3, 21 


d 


sk I/O, 20 


flags, 3 




Function 44 


52 


Function 49 


3 


Function 50 


16 


JMP, 18 




Binary Coded Decimal {BCD) 


f 


elds, 31 




format, 25 




BIOS, 1, 2, 15 


assembling. 


69 




lis, 20 




customizing 


4, 10 


debugging, 100, 103 


d 


sk data structures, 34 


ei 


ror message header, 85 


media flag, 


107, 108 


new functior 


s, 113 




utines, 2 




organizatio 


, 15 


subroutine entry points. 




84 




subroutines 


17 


BIOS entry po 


nts, 15, 49, 


cold start, 


101 


flu5h buffers, 64 


BIOS function 


calls: 





50, 51, 


111, 161 


1 


50, 52, 


111, 161 


2 


50, 55, 


111, 161 


3 


50, 55, 


111, 161 


4 


50, 55, 


112, 161 


5 


50, 56, 


112, 161 


6 


50, 56, 


112, 161 


7 


50, 56, 


112, 161 


9 


50, 59, 


112, 161 


1 


: 50, 59 


112, 161 


1 


: 50, 60 


112, 161 


1 


: 50, 60 


112, 161 


1 


: 50, 61 


113, 161 


1 


: 50, 61 


113, 161 


1 


: 50, 57 


113, 161 


1 


: 50, 62 


113, 161 


1 


i 50, 57 


113, 161 


1 


: 50, 57 


113, 161 


1 


); 50, 58 


113, 161 


2 


: 50, 52 


113, 161 


2 


: 50, 53 


113, 161 


2 


t 50, 53 


113, 161 


2 


t 50, 63 


113, 161 


2 


1: 50, 64 


113, 161 



50, 65, 113, 161 

24, 50, 67, 113, 162 



27i 50, 66, 114, 162 
28: 50, 66, 114, 162 
29! 50, 66, 114, 162 

BIOS functions 

list, 50, 111 to 114 
summary, 161, 162 

BIOS jump vector, 15, 16, 49 
public names, 77 

BIOS Enodules, 71, 73 



al I 



73 



73 



external reference, 73 

functional summary, 71 
BIOSKRNL.ASM, 71 to 73 
equate statement, 71 

n global variables, 76 

modification restriction, 71 
nonbanked system, 71 
public utility subroutines, 
76 
■~| BIJ4, 40, 42 

I block 

defined, 41 

mask, 40, 42 

r~ moves, 15 

I shift factor, 40, 42 

' size restriction, 41 

transfers (memory-to-memory) , 
— 24 

~ blocking logical 

128-byte records, 23 
blocking/deblocking, 53 
in BIOS, 52, 62, 64 
•^ BOOT, 50, 51 

entry point, 100 
' JMP , 16 

BOOT. ASM, 71 

module, 72, 137 
~) boot loader, 102 

module, 137 
BOOT module 

entry points, 77 
■^ boot RCMs, 51 

j BOOT routine, 18 

booting CP/M 3, 102 
BSH, 40, 42 

Buffer Control Block, 34, 39 
~ fields, 45 

format, 44 
buffer definitions, 94 
buffer space, 8, 23 
-I allocation, 15, 93 

I hardware-dependent, 5 

buffering scheme, 8, 23 



buffers, 46 

Blocking/Deblocking, 92 
dirty, 64 
pending, 52 



CCP, 2 

flags, 3 

loading into TPA, 78 
CCP.COM, 13, 18 
character device, 74 

characteristics table, 140 

initialization, 80, 140 

input, 80 

interfacing, 78 

labels, 80 

logical to physical 
redirection, 74 

output, 80 

table (eCTBL), 74 
character l/O, 19 

data structures, 32 

interface routines, 74 

machine-dependent , 79 

Operation, 74 

redirection, 78 
CHARIO.ASM, 71 

module, 140 
CHARIO module, 72, 74, 78 
checksumming 

full directory, 41 
checksum vectors, 34, 38, 88 
CHRTBL, 52, 78 
clear area, 7 
clock support, 15, 24, 67 
clusters 

See block 
Cold Boot 

Loader, 10, 12, 51 
process, 12, 13 
passpoint, 105 
cold start, 10, 101, 137 

initialization, 12 
loader, 15, 19, 101 
common memory, 5, 11, 34, 68 
banked system, 34 
base page, 90 
BIOS data structures, 67 
CONIN, 16, 17, 50, 55 
CONOST, 16, 17, 50, 57 
COMDUT, 16, 17, 50, 55 
Console Command Processor 
See CCP 



12 



console output , 1 2 

call, 3 

CONST, 16, 'so, 55 
COPYSYS utility, 98, 102 
CP/M 2 BIOS 

modification. 111 
CP/M 3 

Linked BIOS Bank/Move 
Module, 152 

customi zing hard wan 

loading into memory 

See also BIOS 
CPM3.SYS, 1 

file, 11, 13, 19 

file format, 115 

loading into memory, ^ 
CPMLDR, 5, 19, 98, 100 

sign-on message, 101 

utility, 100 
CPMLDR_BDOS, 12 
CPMLDR_BIOS, 12 
CPMLDR.COM, 99 
CTRL-C, 39 
CTRL-Z, 19, 54 
Customizing CP/M 3, 11 



block allocation size, 
buffers, 6, 23, 46, 93 
record buffers, 24 
record caching, 23 
region, 10 
data structureo, f 
in common memory 

DDT, 100 

deblocking buffi 
deblocking logii 
records, 23 
debugger, 103 
debugg i ng 

BIOS, 100, 103 
■ '1 SID, 100, 



I, 46, 144 



a, S, 23 
,1 12B-byte 



default 



with question i 
iity select ioi 
■*- '■--, 62 



format, 7S 
DEVICE utility 
DEVINI, 16, 17, 

DEVTBL, 16, 17 



ng. 



lirect Memory Access 
See DMA 

lirectory 
buffers, 23, 34, 46, 92 
caches, 23 
checksumming, 41 
entries, 1, 41, 43 
hashing, 39 
hash tables, 5, 9, 92 



regu 
disk 



.rds, 23 
10 



18, 23 



compatibility, 10 

controller, 83 

density automatically 
determined, 74 

drives, 11, 107, 109 

I/O, 15, 71, 72 

organization, 10 
disk formats 

multiple, 109 

subsystem, 34, 62 
Disk Parameter Block, 23, 34, 
37, 109, 144 

banked system, 34 

DPB macro, 48 

fields, 40 

format, 40 
Disk Parameter Header, 23, 
34, 36, 59, 109, 144 

DPH macro, 47 

fields, 37 

format, 36 

regular, 83 
disks 

distribution, 1 

double density, 42 

number supported, 1 

physical sector size, 44 

reformatting, 42 
DMA, 144 

address, 20 

buffer, 23 

controller, 9 
dollar sign (5) , 115 
DPH 

See Disk Paraaetsr Header 
drive 

characteristics, 12 

default, 90 

table, 36, 74 
drive code 

absolute, 76 



DRVTBL, 17, 50, 53 


G 


JMP, 16 




module, 72, 74, 81 


G command, 10 5 


DRVTBL. ASM, 71 


GENCPM, 6, 11, 12 


dynamic 


command input, 87 


allocation of space, 1 


directory hashing, . 


disk aefinition table, 59 


in banked system, 8: 




in nonbanked system, 


B 


questions, 89, 90 




utility, 23, 36, 46, 


end-of-file, 20 


global variables, 76 


condition, 19, 54 




entry points 




BIOS subroutine, 84 




BOOT, 51 


handshaking 


BOOT modale, 77, 78 


polled, 57, 58 


flush buffers, 64 


hardware 


MOVE module, 86 


configurations, 2 
initialization, 13, 


WBOOT, 52 


entry values, 27 


requirements, 1 


equates 


supported, 10, 11 


absolute external, 27 


special CMA, 65 


for Mode Byte Bit Fields, 131 


hardware environment. 


erased character, 90 


banked system, 11 


error 


nonbanked system, 11 
hash table, 39 


code, 24, 31 


handling, 84 


directory, 9, 92 


in multieector transfer, 63 


searches, 107 


nonrecoverable, 85 


head number, 37 


error messages 


hexadecimal address, 4 


extended, 1, 30 


high-order 


in foreign language, 32 


bit, 43 


long, 91 


byte, 27 


short, 30 


nibble, 7 9 


Extended Disk Parameter 


HOME, X6, 50, 58 


Header (XDPH), 72, 74, 81 




fields, 83 


I 


format, 82 




Extent mask, 41 


I/O, 2 




character, 19, 74, 7 


¥ 


devices, 11 




disk, 20, 74 


file 


drivers, 71 


CPM3.SYS format, 115 


multiple sector, 85 


random access, 1 


Port Addresses, 153 


storage, 10 


ports, 78 


structure, 1 


redirection, 20 


first-time initialization 


simple device, 3 


code, 83 


IBM 3740 disk, 10 


flag, 27 


INIT, 83, 84 


global system, 30 




media, 37 




FLUSH, 16, 50, 64 





initialization 

basic system, 51 
cold start, 12 
hardware, 51, 77 
Page Zero, 18, 51 
system tracks, 102 
input, 140 
input/output 

See I/O 
interbank moves, 86 
intrabank moves, 86 
lOBYTE facility, 52 



JMP, 16, 18 






15, 16, 77 



100 
LDBBIOS, 12, 51, 100 

length restriction, 100 

linking, 100 
LDRBIOS.ASM, assembling, 100 
Least Recently Used (LfU) 

buffering, 8, 23 
LINK 

field, 44 

L option, 100 
LINK-80, 69, 73 
linker, 27 

LIST, 16, 17, 50, 56 
LISTST, 16, 17, 50, 57 
location zero, 6 

character device 

combinations, 54 
device characteristics, 19 
device reassigning, 20 
drive, 144 
read operation, 62 
record blocking/deblocking, 

23 
records, 3 
sequent 1 al sector 
address, 62 
LOGIN, 83, 84 
low-order 



LtV buffering scheme, 8, 23 



automatic type 

deter mi nat ion 
change, 107 
flag, 37, 108 



.vable 



107 



43 



byte. 



memory 

addresses, 12 
configurations, 1 
contiguous, 6, 11 

organization, 6 

selects, 15 

top of banked, 5, t 
memory-mapped video 

display, 19 
memory organization 

banked, 5, 6, 8 

general, 3 , 4 

nonbanked, 7-9 

memory requirements, 

banked system, 7 

nonbanked, 7 

segment table, 92 
memory-to- memory mov 

bits, 79 
byte, 32 
modules 

communica 

MOVE, 16, 17, 24, 50, 65 
MOVE. ASM, 71, 73 
MOVE Module, 85 

entry points, 86 
MOVES 

interbank, 86 

intrabank, 86 
MULTIO, 16, 17, 20, 23, 50, 
multiple sector read or wri 

operations, 20 
mult i sector transfer, 63 



external, 73 
public, 73 
user-defined, 73 



I between. 



nonbank-awitched memory, 
block moves and memory 






. 1, 7 



39 



L e ^u ±Lti men ^s 

nonbanked BIOS 
assembling, t>» 
debugging, 103 
linking, 69 

nonbanked memory, 4 

nonbanked system 

allocation vector, _ 
buffer control block 
configuration, 9 

number of lines per 
page, 90 



OFF field, 43 

OPEN, 18 

operating system bank, 9 

operating system modules 

banked, 5 

resident, 5 
output, 140 
overlay 

data buffer, 94 

directory buffer, 93 



transfer, 23 

translation, 62 
PORTS. LIB, 153 
Print Record, 115 
printers, 11 

data items, 159 
definitions, 129 
entry points, 157 
names, 77 

symbols defined in module 
75 
public variables, 129 
names, 17 
predefined, 75 



question variable, 68 
questions 

GENCPM, 89 to 94 



P command, 105 

Page Zero, 4, 5, 18, 

pasBpoint, 105 

cold BOOT routine, 

in BIOS, 104 
password protect ion, 
peripheral 

single, 20 

types, 12 
peripheral device 

I/O, 2 

reassigning, 20 
physical 

devices, 20 

disk unit, 144 

I/O, 2 
physical record 

buffers, 107 

mask, 41, 44 

shift factor, 41, 4 



READ, 16 to 23, 50, 61, 



Register A, 17, 20 

removable drives 

BIOS media flag, 107, 108 
directory hashing, 107 
performance penalty, 107 

RESERVl, 16, 51 

RESERV2, 16, 51 

Resident System Extension (J 
Modules, 3 

residual multiseotor count, 

retry routine, 84 

returned values, 27 

RMAC, 69, 73, 99, 117 

root module, 81, 85 

rotational latency, 63 

RSX entry point, 8 

Rubout , 90 



SCB, see SysteB Control 


Block 


components, 2 


SCB.ASM, 71 




generation (GENCPM), 7, 39 


file, 17, 27, 28 




initialization, 15, 18, 77 


module. 72, 129 




labels, 27 


scratchpad area, 34, 38 




loader program (CPMLDR), 13 


sector 




printer, 19 


address, 37 




start-up, 3, 11 


skew factors, 37 




time and date, 15 


SECTHN, 16, 50, 62 




System Control Block (SCB) 


SELDSK, 21, 23, 50, 59, 


109 


definition, 17 


JMP, 16 




disk organization, 10 


routine, 74, 109 




error mode variable, 24 


SEIJ4EM, 16, SO, 66 




external labels, 27 


separate buffer pools, 8, 23 


fields, 3 


sequential 




system tracks, 10, 18, 19 


file input, 12 




initialization, 102 


read, 23 




sample CP/M 3 organization. 


serial devices, 74 




99 


baud rates, 79 






SETBNK, 16, 23, 50, 66 




T 


SETDMA, 16, 20, 21, 23, 


50, 60 




SETSEC, 16, 21, 23, 50, 


60 


target system, 12 


SETTRK, 16, 21, 23, SO, 


S9 


TIME, 16, 17, 50, 67 


SID, 100, 103, 105 




time of day 


G command, 104 




function, 24 


1 command, 104 




clocka. 78 


L command, 104 




top of memory, 5-6, 90 


sign-on message, 13, 101 


tracing routines, 105 


single-density 




track address, 37 


disX handler Z80 DMA, 


144 


Transient Program Area 


floppy disk drive, 11 




(TPA), 2, 32 


skew factor, 62 




transient programs, 5, 18 


skew table 




TYPE, 83 


address, 62 






SKEW macro, 48 




U 


space allocation, 6 






starting 




UNIT, 83 


disk transfer address 


76 


user Interface, 2 


sector, 76 




USERP, 16, 51 


track, 76 






status palling, 140 




V 


subroutines 






empty, 15 




variables 


names, 17 




global, 76 


symbols, public, 75 




public, 17, 75, 129 
vectors 

allocation, 38 

checksum, 38 

I/O redirection bit, 54 



Warm BOOT routine, 3 
warm start, 10, 137 
WBOOT, 50, 52 

entry point, 52 

JMF, 16 

routine, X8 
WRITE, 16, 20, 21, 23, 50, 
83, 84 



XDPH, 72, 74, 81 

fields, 83 

format, 82 
XMOVE, 16, 24, 50, 65, 
XON/XOFF protocol, 32 
XREF, 117 



NOTES 



NOTES 



NOTES 



NOTES 



NOTES 



NOTES 



NOTES 



Reader Comment Card 

We welcome your comments and suggestions. They help us provide you with better 
product documentation. 



1. What sections of this manual are especially helpful? 



I ' 2. What suggestions do you have for improving this manual? What information 

is missing or incomplete? Where are examples needed? 



3. Did you find errors in this manual? (Specify section and page number.) 



CP/M Plus^" (CP/M® Version 3) Operating System User's Guide 

Second Edition: I 

1006-2003-002 



P Second Edition: March 1983 



COMMENTS AND SUCCtSTKDNS BECOME THE PROPERTY OF DIGITAL RESEARCH. 



m 
in 

I? 



303 


Sc 


oCO 


lz 


"m 


SCO 


^w 




^JU 


Sm 


3-0 


s^ 


;=< 


S!> 


3r- 



n 

11 Reader Comment Card 

-^ We welcome your comments and suggestions. They help us provide you with better 
; [ product documentation. 



1. What sections of this manual are especially helpful? 



2. What suggestions do you have for improving this manual? What information 
is missing or incomplete? Where are examples needed? 



3. Did you find errors in this manual? {Specify section and page number.) 



^ CP/M Plus™ (CP/M® Version 3) Operating Systenn Programmer's Guide 

I i Second Edition: April 1983 

' ' 1006-2023-002 

n COMM£Isn3 AND SUGGESTIONS BECOME THE PROrtRTY OF DIOTAL RESEARCH. 






|D3 


»C 


oC/) 


|z 


^ m 


SCO 


SCO 




f.^ 


5-0 


s^ 


»:< 


Bi> 


5r- 



Reader Comment Card 

We welcome your comments and suggestions. They help us provide you with better 
product documentation. 



1. What sections of this manual are especially helpful? 



I ' 2. What suggestions do you have for improving this manual? What information 
is missing or incomplete? Where are examples needed? 



n 

3. Did you find errors in this manual? (Specify section and page number.) 

n 



CP/M Plus" (CP/M® Version 3) Operating System System Guide 
n Second Edition: July 1983 

' ' 1006-2013-002 

COMMENTS AND SUGCESTXJNS BECOME THE PROPERTY OF DIOTAL RESEARCH, 



= 03 


°lC 


pW 


!s? 


-0 m 


?!C0 


2(0 




SJU 


„m 


= -0 


s^ 


k< 


BJ> 


sr- 



^